Постпроцессинг

Постпроцессинг в контексте MDX — это этап, который следует после первичной компиляции MDX-файла в JavaScript-код. Он позволяет модифицировать итоговую структуру, добавлять обертки, интегрировать кастомные компоненты и выполнять оптимизации, которые невозможно сделать на этапе парсинга. Этот процесс критически важен для проектов, где Markdown используется совместно с React-компонентами.

Принцип работы постпроцессинга

MDX-компилятор сначала преобразует содержимое .mdx в AST (Abstract Syntax Tree) на основе Markdown и JSX-синтаксиса. После этого AST превращается в JavaScript-код. Постпроцессинг позволяет вмешиваться на любом из двух уровней:

  1. На уровне AST — добавление узлов, изменение структуры дерева, применение плагинов для синтаксиса Markdown или JSX.
  2. На уровне сгенерированного кода — изменение итогового JavaScript-кода, внедрение импорта компонентов, автоматическое оборачивание в HOC (Higher-Order Component).

Плагины для постпроцессинга

MDX поддерживает плагины для обработки контента как на этапе компиляции, так и после. Их можно разделить на три категории:

  1. Remark-плагины — работают на уровне Markdown. Позволяют:

    • Автоматически генерировать оглавления;
    • Подсвечивать синтаксис кода;
    • Добавлять кастомные атрибуты к тегам.

  2. Rehype-плагины — работают с HTML-представлением AST. Возможности:

    • Внедрение оберток для всех <h1>-<h6> заголовков;
    • Автоматическая генерация ссылок на заголовки;
    • Оптимизация изображений и вставка lazy-loading атрибутов.

  3. MDX-плагины — непосредственно модифицируют JSX-выход:

    • Оборачивание каждого элемента <p> в кастомный компонент;
    • Динамическая подгрузка интерактивных виджетов;
    • Внедрение глобальных импортов для всех MDX-файлов проекта.

Настройка постпроцессинга

Для конфигурации используется объект mdxOptions при вызове функции compile из пакета @mdx-js/mdx:

import { compile } from '@mdx-js/mdx';
import remarkSlug from 'remark-slug';
import rehypeAutolinkHeadings from 'rehype-autolink-headings';

const mdxOptions = {
  remarkPlugins: [remarkSlug],
  rehypePlugins: [rehypeAutolinkHeadings],
  providerImportSource: '@mdx-js/react'
};

const compiledMDX = await compile('# Заголовок\n\nТекст', mdxOptions);

В этом примере:

  • remarkSlug добавляет уникальные ID для всех заголовков;
  • rehypeAutolinkHeadings автоматически оборачивает заголовки в ссылки;
  • providerImportSource позволяет использовать контекст MDXProvider для глобальных компонентов.

Автоматическая обертка контента

Для унификации стилей или добавления дополнительной логики часто используют обертки на уровне JSX:

import { MDXProvider } from '@mdx-js/react';
import CustomParagraph from './CustomParagraph';

const components = {
  p: CustomParagraph
};

export default function MDXContent({ content }) {
  return (
    <MDXProvider components={components}>
      {content}
    </MDXProvider>
  );
}

Каждый элемент <p> будет автоматически заменён на CustomParagraph, что обеспечивает единообразие оформления текста и возможность внедрять интерактивные функции.

Оптимизация кода через постпроцессинг

Постпроцессинг позволяет производить оптимизацию кода и контента:

  • Tree-shaking импорта — автоматическое удаление неиспользуемых компонентов;
  • Минификация HTML/JSX — уменьшение объема итогового бандла;
  • Сортировка и фильтрация блоков контента — полезно для генерации документации, где порядок элементов может быть динамическим.

Практические советы

  • Всегда проверять совместимость плагинов: remark-плагины работают до JSX, а rehype — после.
  • Для крупных проектов создавать отдельный файл конфигурации mdx.config.js, чтобы избежать дублирования настроек.
  • Использовать функцию compile вместо старого @mdx-js/mdx.sync, если нужен асинхронный постпроцессинг с динамическими плагинами.
  • При обертке компонентов учитывать ключи React (key) для списков, чтобы избежать ошибок рендеринга.

Постпроцессинг в MDX — мощный инструмент, позволяющий гибко управлять контентом, интегрировать его с React-компонентами и оптимизировать вывод. Правильная настройка плагинов и оберток обеспечивает чистый, поддерживаемый и расширяемый код MDX.

Оглавление