Популярные плагины для MDX

Библиотека MDX интегрируется с экосистемой remark и rehype, что позволяет обрабатывать Markdown и HTML на разных этапах компиляции. remark-плагины работают на уровне синтаксического дерева Markdown (MDAST), а rehype-плагины — на уровне дерева HTML (HAST).

Примеры популярных remark-плагинов:

  • remark-slug — добавляет уникальные идентификаторы к заголовкам для удобного создания ссылок.
  • remark-autolink-headings — автоматически оборачивает заголовки в ссылки с якорями.
  • remark-gfm — добавляет поддержку GitHub Flavored Markdown (таблицы, зачеркивания, списки задач).

Примеры популярных rehype-плагинов:

  • rehype-highlight — подсветка синтаксиса кода с использованием highlight.js.
  • rehype-stringify — преобразует дерево HTML обратно в строку, необходимый этап для окончательной генерации MDX.
  • rehype-slug — аналог remark-slug, добавляет идентификаторы к заголовкам на уровне HTML.

Настройка плагинов осуществляется через объект конфигурации MDX:

import { compile } from '@mdx-js/mdx';
import remarkGfm from 'remark-gfm';
import rehypeHighlight from 'rehype-highlight';

const mdxContent = `
# Пример заголовка
\`\`\`js
console.log('Hello, MDX!');
\`\`\`
`;

const compiled = await compile(mdxContent, {
  remarkPlugins: [remarkGfm],
  rehypePlugins: [rehypeHighlight],
});

@mdx-js/react

Плагин @mdx-js/react позволяет использовать React-компоненты внутри MDX-документов и управлять их рендерингом через MDXProvider. Это обеспечивает возможность глобальной замены элементов Markdown на кастомные компоненты.

Пример использования:

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

const components = {
  h1: MyHeading,
};

function App({ children }) {
  return <MDXProvider components={components}>{children}</MDXProvider>;
}

В данном случае все заголовки h1 в MDX будут заменены на компонент MyHeading.

Ключевой момент: MDXProvider поддерживает все HTML-теги Markdown (p, h1, h2, ul, li, code) и позволяет создавать глобальный стиль отображения контента без изменения исходного MDX.

mdx-bundler

mdx-bundler — инструмент для компиляции MDX в исполняемый JavaScript-код с поддержкой ESM. Он сочетает в себе возможности esbuild и MDX, обеспечивая высокую производительность при работе с большим количеством MDX-документов.

Особенности:

  • Поддержка TypeScript внутри MDX.
  • Возможность импорта локальных компонентов и модулей.
  • Настройка remark и rehype плагинов для каждой компиляции.

Пример использования:

import { bundleMDX } from 'mdx-bundler';

const result = await bundleMDX({
  source: mdxContent,
  mdxOptions(options) {
    options.remarkPlugins = [...(options.remarkPlugins || []), remarkGfm];
    options.rehypePlugins = [...(options.rehypePlugins || []), rehypeHighlight];
    return options;
  },
});

const { code } = result; // скомпилированный JS-код для рендеринга

mdx-bundler особенно полезен для статических сайтов и блогов, где нужно динамически генерировать страницы из MDX с кастомными компонентами и плагинами.

next-mdx-remote

Для интеграции MDX с фреймворком Next.js используется next-mdx-remote. Он позволяет рендерить MDX контент на сервере и передавать готовый HTML в компонент страницы без необходимости компиляции на клиенте.

Пример:

import { serialize } from 'next-mdx-remote/serialize';
import { MDXRemote } from 'next-mdx-remote';

export async function getStaticProps() {
  const mdxSource = await serialize('# Пример MDX', { remarkPlugins: [remarkGfm] });
  return { props: { mdxSource } };
}

export default function Page({ mdxSource }) {
  return <MDXRemote {...mdxSource} />;
}

Преимущество: поддержка серверного рендеринга и оптимизация производительности страниц с MDX.

remark-frontmatter и rehype-meta

Для работы с метаданными MDX-документов используются плагины remark-frontmatter и rehype-meta. Они позволяют извлекать YAML или TOML блоки с настройками документа и использовать их внутри React-компонентов.

Пример YAML-фронтматтера:

---
title: "Пример документа"
date: "2026-03-23"
tags: ["mdx", "javascript"]
---
# Контент документа

С помощью этих плагинов можно парсить фронтматтер и передавать метаданные в компоненты, например для генерации заголовков страниц или списка тегов.

remark-code-titles

Плагин remark-code-titles добавляет заголовки к блокам кода, что особенно удобно для документации. Заголовок определяется как первая строка блока комментария:

```js:title=example.js
console.log('Hello, world!');

На выходе получится визуально выделенный блок с названием файла `example.js`. Такой подход улучшает читаемость кода в учебных материалах и блогах.

---

### rehype-accessible-emojis

Плагин `rehype-accessible-emojis` преобразует эмодзи в доступные для screen reader элементы, улучшая UX и доступность контента. Он заменяет графические эмодзи на `<span>` с `aria-label`, что важно для образовательных и корпоративных MDX-документов.

---

Эти плагины формируют экосистему MDX, позволяя гибко кастомизировать Markdown и HTML, интегрировать React-компоненты, управлять фронтматтером и улучшать доступность. Комбинация remark и rehype плагинов обеспечивает максимальный контроль над преобразованием контента на всех этапах компиляции.
Оглавление