Структура Markdown документа

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

Основные элементы структуры

  1. Заголовки (Heading) Заголовки определяют иерархию документа и делят его на разделы. В Markdown заголовки обозначаются символами # от одного до шести:

    # H1
## H2
### H3

    В абстрактной синтаксической структуре (AST) библиотеки Remark заголовок представлен узлом типа heading с полями:

    • depth: уровень заголовка (1–6)
    • children: массив текстовых или инлайн-узлов, формирующих содержимое заголовка

  2. Абзацы (Paragraph) Абзацы — основной блок текста. В AST узел paragraph содержит массив children, где каждый элемент — текст, эмодзи, инлайн-разметка или ссылки.

  3. Списки (List) Markdown поддерживает нумерованные и маркированные списки:

    • Маркированные списки: -, *, +
    • Нумерованные: 1., 2. и т.д. В AST list имеет поля:
    • ordered: булево значение, определяющее тип списка
    • start: начальный индекс нумерованного списка
    • spread: определяет, является ли список разнесённым (с пустыми строками между элементами)
    • children: массив узлов listItem

  4. Элементы списка (ListItem) Каждый элемент списка представляет собой узел listItem. Он содержит children, которые могут быть параграфами, подсписками или другими блоками.

  5. Ссылки и изображения (Link, Image)

    • link имеет поля url, title и массив children с текстом ссылки
    • image хранит url, alt и title

  6. Кодовые блоки (Code) Блоки кода обозначаются тройными обратными кавычками или отступами. Узел code имеет:

    • lang: язык кода
    • value: содержимое блока

  7. Цитаты (Blockquote) Узел blockquote содержит массив children, который может включать параграфы, списки и другие блоки. Markdown использует для этого символ >.

Инлайн-элементы

Инлайн-элементы формируют содержимое абзацев и заголовков:

  • Текст (Text) — простой текст без разметки
  • Выделение (Emphasis, Strong) — курсив и жирный текст
  • Код (InlineCode) — инлайновый код
  • Ссылки и изображения (Link, Image) — упомянутые выше

Каждый инлайн-элемент в AST вложен в родительский блок (paragraph, heading) через поле children.

Разметка и AST

Remark анализирует Markdown и строит дерево узлов (AST, MDAST — Markdown AST). Каждая сущность документа представлена отдельным узлом с типом и метаданными. Пример структуры AST для простого документа:

{
  "type": "root",
  "children": [
    {
      "type": "heading",
      "depth": 1,
      "children": [{"type": "text", "value": "Заголовок"}]
    },
    {
      "type": "paragraph",
      "children": [{"type": "text", "value": "Текст абзаца"}]
    },
    {
      "type": "list",
      "ordered": false,
      "children": [
        {
          "type": "listItem",
          "children": [{"type": "text", "value": "Первый элемент"}]
        }
      ]
    }
  ]
}

Трансформация в HTML с Rehype

Rehype работает с HTML AST (HAST) и применяется после Remark для генерации HTML. Основные узлы HAST:

  • element — HTML-тег с атрибутами и дочерними узлами
  • text — текстовый контент внутри элемента
  • comment — HTML-комментарии

Remark и Rehype связаны через плагин remark-rehype, который преобразует MDAST в HAST. Это позволяет применять HTML-специфические плагины, изменять атрибуты элементов и настраивать вывод.

Особенности работы с деревьями

  • AST является рекурсивной структурой, что позволяет легко обходить и модифицировать узлы.
  • Каждый блок может содержать инлайн-узлы, а узлы списков и цитат могут содержать блоки.
  • Понимание вложенности важно для точного преобразования Markdown в HTML, PDF или другие форматы.

Практические рекомендации

  • Использовать unified для построения конвейера обработки текста: парсинг → трансформация → генерация.
  • Разделять обработку блоков и инлайнов для более точного контроля над контентом.
  • Подключать плагины Remark для синтаксического анализа, Rehype для визуального представления и оптимизации HTML.
  • Тестировать преобразования на сложных документах с вложенными списками, цитатами и кодом, чтобы убедиться в корректности AST.

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

Оглавление