Плагин remark-rehype: принципы работы

remark-rehype — это мост между двумя экосистемами обработки контента в Jav * aScript: Markdown и HTML. Библиотека Remark специализируется на анализе и трансформации Markdown в виде абстрактного синтаксического дерева (MDAST), тогда как Rehype работает с HTML-структурами через HAST (Hypertext Abstract Syntax Tree). Плагин remark-rehype обеспечивает конвертацию MDAST в HAST, сохраняя семантику документа и позволяя далее использовать мощные инструменты обработки HTML.

Основные принципы работы

  1. Преобразование структур Remark создает дерево MDAST, где каждый узел соответствует элементу Markdown: заголовки, списки, параграфы, ссылки, изображения. Remark-rehype преобразует эти узлы в эквивалентные HTML-узлы HAST. Например:

    • heading → <h1>–<h6>
    • paragraph → <p>
    • list → <ul> или <ol>
    • listItem → <li>

  2. Сохранение метаданных В процессе конвертации плагин переносит свойства узлов, такие как:

    • id для заголовков
    • alt для изображений
    • title для ссылок Эти данные важны для генерации семантически корректного HTML.

  3. Настраиваемость через опции Remark-rehype поддерживает конфигурацию:

    • allowDangerousHtml — позволяет включать встроенный HTML из Markdown без экранирования.
    • handlers — кастомные функции для обработки нестандартных узлов или специфических требований к HTML.
    • unknownHandler — механизм обработки неизвестных типов узлов, предотвращающий потерю контента.

Процесс конвертации

  1. Анализ Markdown Markdown передается в Remark, который строит MDAST. Дерево хранит:

    • тип узла (type)
    • дочерние элементы (children)
    • текстовое содержимое (value)

  2. Проход по дереву MDAST Remark-rehype рекурсивно обходит каждый узел. Для каждого типа определен соответствующий обработчик:

    • стандартные узлы преобразуются автоматически
    • нестандартные могут быть переназначены через handlers

  3. Генерация HAST В ходе обхода создается дерево HAST:

    • element для HTML-тегов
    • text для текстового содержимого
    • comment для HTML-комментариев Это дерево полностью совместимо с Rehype-плагинами для последующей трансформации или рендеринга.

Важные особенности

  • Поддержка встроенного HTML Markdown-документы часто содержат raw HTML. Без специальной настройки Remark-rehype будет экранировать HTML-теги, чтобы избежать их интерпретации. Включение опции allowDangerousHtml сохраняет HTML без изменений.

  • Кастомные обработчики (handlers) Позволяют расширять функциональность. Например, можно преобразовать нестандартный блок :::note в <aside class="note">. Handler получает узел MDAST и возвращает узел HAST.

  • Слияние с Rehype-плагинами После конвертации MDAST в HAST дерево становится доступным для всех Rehype-плагинов: минификация, добавление атрибутов, генерация таблицы содержания, преобразование в JSX и т.д.

Пример структуры узлов

MDAST (Markdown)

{
  "type": "paragraph",
  "children": [
    { "type": "text", "value": "Пример текста" },
    { "type": "link", "url": "https://example.com", "children": [{ "type": "text", "value": "ссылка" }] }
  ]
}

HAST (HTML)

{
  "type": "element",
  "tagName": "p",
  "children": [
    { "type": "text", "value": "Пример текста" },
    { "type": "element", "tagName": "a", "properties": { "href": "https://example.com" }, "children": [{ "type": "text", "value": "ссылка" }] }
  ]
}

Принципы интеграции в workflow

  • Remark → Remark-плагины → remark-rehype → Rehype-плагины → HTML/JSX Такая цепочка позволяет модульно расширять функциональность, разделяя этапы парсинга Markdown, трансформации дерева и финальной генерации HTML.

  • Сохранение семантики Плагин гарантирует, что каждый Markdown-элемент будет представлен в HTML максимально близко к исходной структуре и смыслу документа.

  • Оптимизация производительности Конвертация происходит рекурсивно и лениво: узлы обрабатываются по мере обхода дерева, что уменьшает нагрузку при больших документах.

Типичные сценарии использования

  • Генерация статических сайтов с Markdown-контентом
  • Конвертация документации в HTML/React-компоненты
  • Преобразование Markdown в PDF или другие форматы через промежуточное HTML
  • Настройка специфичных блоков и компонентов с помощью кастомных handler-функций

Remark-rehype выступает не просто как конвертер, а как гибкая основа для построения цепочек обработки контента, обеспечивая полное взаимодействие между Markdown и HTML-экосистемами.

Оглавление