Корневые узлы и их свойства

В библиотеке Remark и её экосистеме для работы с Markdown и HTML корневой узел играет центральную роль. Корневой узел — это объект верхнего уровня в дереве синтаксического анализа (AST, Abstract Syntax Tree), который содержит все дочерние узлы документа. Понимание структуры корневого узла и его свойств позволяет управлять обработкой документа, трансформацией контента и генерацией конечного HTML или Markdown.

Структура корневого узла

Корневой узел в Remark и Rehype имеет стандартную структуру:

{
  type: 'root',
  children: [],
  position: { start: {...}, end: {...} }
}

  • type — всегда 'root'. Определяет тип узла, что позволяет парсерам и плагинам корректно идентифицировать его.

  • children — массив дочерних узлов. Каждый дочерний узел может быть другим типом: параграф (paragraph), заголовок (heading), список (list), текст (text) и т.д. Для HTML через Rehype дочерние узлы соответствуют элементам DOM: element, text, comment.

  • position — объект, описывающий положение узла в исходном тексте:

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

Основные свойства корневого узла

  1. children

    • Массив объектов, представляющих содержимое документа.
    • Каждый объект имеет свой type и может содержать свои children.
    • Пример структуры дочернего узла Markdown:
{
  type: 'paragraph',
  children: [
    { type: 'text', value: 'Пример текста.' }
  ]
}
  • Для HTML через Rehype:
{
  type: 'element',
  tagName: 'p',
  properties: {},
  children: [
    { type: 'text', value: 'Пример текста.' }
  ]
}

  1. data

    • Произвольный объект для хранения метаданных.
    • Плагины могут использовать data для добавления информации о корневом узле.
    • Пример:
root.data = { title: 'Документ', author: 'Имя Автора' };

  1. position

    • Свойство, автоматически добавляемое парсером, если включена опция position: true.
    • Полезно для отладки и отображения ошибок.

Работа с дочерними узлами

  • Добавление новых узлов:
root.children.push({
  type: 'paragraph',
  children: [{ type: 'text', value: 'Новый параграф' }]
});
  • Фильтрация узлов по типу:
const headings = root.children.filter(node => node.type === 'heading');
  • Рекурсивная обработка узлов:
function traverse(node, callback) {
  callback(node);
  if (node.children) {
    node.children.forEach(child => traverse(child, callback));
  }
}

Различия между Remark и Rehype

Свойство Remark (Markdown AST) Rehype (HTML AST)
Тип корневого узла root root
Дочерние узлы paragraph, heading, text element, text, comment
Метаданные data data
Позиция в тексте position position
  • Remark ориентирован на Markdown-синтаксис, где типы узлов описывают логическую структуру текста.
  • Rehype ориентирован на HTML, где узлы ближе к DOM, и свойства включают tagName и properties.

Практические приёмы использования корневого узла

  1. Анализ структуры документа Корневой узел позволяет полностью просканировать документ, подсчитать заголовки, списки, параграфы и собрать статистику.

  2. Трансформация документа Изменение содержимого возможно через модификацию children корневого узла или отдельных подузлов. Например, конвертация всех заголовков в заголовки второго уровня:

traverse(root, node => {
  if (node.type === 'heading') {
    node.depth = 2;
  }
});
  1. Генерация Markdown или HTML После обработки AST с помощью корневого узла можно использовать remark-stringify или rehype-stringify для генерации конечного текста.

Корневой узел является фундаментом для всех операций с AST в Remark и Rehype. Он определяет структуру документа, хранит дочерние узлы и позволяет интегрировать метаданные, позиционные данные и трансформации. Глубокое понимание его свойств обеспечивает эффективное управление контентом и создание сложных плагинов для анализа и модификации Markdown и HTML.

Оглавление