Rehype плагины

Rehype — это инструмент для обработки HTML-деревьев в формате hast (HTML Abstract Syntax Tree). В экосистеме MDX Rehype-плагины используются для модификации сгенерированного HTML, который получается после преобразования MDX-контента. Они позволяют внедрять кастомные атрибуты, добавлять обертки, изменять структуру элементов или выполнять любые другие трансформации HTML.

Установка и подключение Rehype-плагинов

Для работы с Rehype-плагинами необходимо установить соответствующий пакет:

npm install rehype-react

В MDX-конфигурации плагины подключаются через объект mdxOptions:

import rehypeSlug from 'rehype-slug';
import rehypeAutolinkHeadings from 'rehype-autolink-headings';

const mdxOptions = {
  rehypePlugins: [
    rehypeSlug,
    [rehypeAutolinkHeadings, { beh * avior: 'wrap' }]
  ]
};

Объяснение ключевых моментов:

  • rehypeSlug добавляет атрибут id ко всем заголовкам, что позволяет использовать якорные ссылки.
  • rehypeAutolinkHeadings автоматически оборачивает заголовки в ссылку на сам заголовок. Опция beh * avior: 'wrap' указывает, что ссылка оборачивает весь заголовок.

Структура Rehype-плагина

Rehype-плагин — это функция, принимающая объект AST и выполняющая модификации:

function myRehypePlugin() {
  return (tree) => {
    visit(tree, 'element', (node) => {
      if (node.tagName === 'p') {
        node.properties = node.properties || {};
        node.properties.className = 'custom-paragraph';
      }
    });
  };
}

Разбор ключевых моментов:

  • tree — это объект AST, представляющий HTML-документ.
  • visit — утилита для обхода дерева. Часто используется из пакета unist-util-visit.
  • node.tagName проверяет тип HTML-элемента.
  • node.properties позволяет добавлять или изменять атрибуты.

Популярные Rehype-плагины

rehype-highlight

Добавляет подсветку синтаксиса для блоков кода. Используется вместе с библиотекой highlight.js.

import rehypeHighlight from 'rehype-highlight';

const mdxOptions = {
  rehypePlugins: [rehypeHighlight]
};

rehype-raw

Позволяет обрабатывать встроенный HTML внутри MDX, преобразуя его в AST. Важно использовать с осторожностью, так как включение сырого HTML может быть небезопасным.

import rehypeRaw from 'rehype-raw';

const mdxOptions = {
  rehypePlugins: [rehypeRaw]
};

Автоматически добавляет атрибуты target="_blank" и rel="noopener noreferrer" к внешним ссылкам.

import rehypeExternalLinks from 'rehype-external-links';

const mdxOptions = {
  rehypePlugins: [[rehypeExternalLinks, { target: '_blank', rel: ['noopener'] }]]
};

Кастомизация Rehype-плагинов

Rehype-плагины позволяют создавать собственные правила обработки AST:

function rehypeAddDataAttributes() {
  return (tree) => {
    visit(tree, 'element', (node) => {
      if (node.tagName === 'img') {
        node.properties = node.properties || {};
        node.properties['data-loaded'] = 'true';
      }
    });
  };
}

Пример добавляет атрибут data-loaded="true" ко всем изображениям. Такие подходы позволяют внедрять метаданные, управлять анимацией, адаптировать структуру DOM под конкретные требования.

Порядок применения Rehype-плагинов

Плагины применяются последовательно в том порядке, в котором они указаны в массиве rehypePlugins. Это важно, если один плагин зависит от результатов работы другого. Например, rehypeSlug должен применяться перед rehypeAutolinkHeadings, чтобы ссылки создавались на уже существующие id.

Интеграция с Remark-плагинами

MDX позволяет комбинировать Remark-плагины (для Markdown) и Rehype-плагины (для HTML):

import remarkGfm from 'remark-gfm';
import rehypeSlug from 'rehype-slug';

const mdxOptions = {
  remarkPlugins: [remarkGfm],
  rehypePlugins: [rehypeSlug]
};

Это дает гибкость: сначала Markdown преобразуется в AST с помощью Remark, потом HTML модифицируется Rehype.

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

  • Проверять совместимость с версиями MDX и React, особенно при использовании сторонних Rehype-плагинов.
  • Использовать unist-util-visit для обхода и модификации AST, избегая прямой рекурсии.
  • Минимизировать побочные эффекты: изменять только необходимые узлы дерева.
  • Комбинировать Rehype и Remark-плагины для расширенных сценариев: таблицы, подсветка кода, авто-якоря, обработка встроенного HTML.

Хотите, я подготовлю подробный пример MDX-конфигурации с несколькими Rehype-плагинами и кастомным плагином, полностью готовый к использованию в проекте?

Оглавление