Работа с пространствами имен

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

Понятие пространства имен

В контексте AST пространства имен (namespace) — это логическая группа или область, которая определяет, как интерпретировать и валидировать узлы. Они позволяют различать узлы, которые могут иметь одинаковое имя, но разное поведение, в зависимости от контекста.

Markdown-узлы (Remark) находятся в пространстве имен md.
HTML-узлы (Rehype) находятся в пространстве имен html.
При конверсии из Markdown в HTML используется промежуточная обработка узлов, где можно создавать собственные пространства имен для плагинов.

Пространства имен позволяют избежать конфликтов между плагинами и поддерживать строгую типизацию узлов.

Определение пространства имен

В Remark и Rehype пространство имен чаще всего задается через тип узла и его свойства. Для Markdown узлов используется поле type:

const paragraphNode = {
  type: 'paragraph', // пространство имен md
  children: [
    { type: 'text', value: 'Пример текста' }
  ]
};

Для HTML-узлов:

const divNode = {
  type: 'element', // пространство имен html
  tagName: 'div',
  properties: { className: ['container'] },
  children: []
};

Отличие заключается в том, что md-узлы ориентированы на структурную разметку Markdown, а html-узлы — на синтаксис HTML и атрибуты элементов.

Преобразование между пространствами имен

Частая задача — преобразовать Markdown в HTML, сохраняя контекст и корректно распределяя пространства имен. Это делается через унифицированный конвейер unified, который объединяет парсеры, плагины и транспилеры.

import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkRehype from 'remark-rehype';
import rehypeStringify from 'rehype-stringify';

const processor = unified()
  .use(remarkParse) // md пространство
  .use(remarkRehype) // конвертация в html пространство
  .use(rehypeStringify); // генерация HTML

const markdown = '# Заголовок\n\nПараграф текста';
const html = await processor.process(markdown);
console.log(String(html));

remarkRehype отвечает за трансляцию узлов из Markdown-пространства (md) в HTML-пространство (html). Важно понимать, что при этом сохраняются данные узлов, такие как текст, ссылки, атрибуты, но структура меняется.

Создание пользовательских пространств имен

Плагины Remark/Rehype могут определять свои пространства имен для внутренних целей. Это полезно, если нужно обрабатывать специфические типы узлов:

function remarkCustomNamespace() {
  return (tree) => {
    visit(tree, 'paragraph', (node) => {
      node.namespace = 'custom-md';
    });
  };
}

В этом примере каждому узлу параграфа присваивается пространство имен custom-md. Оно позволяет другим плагинам идентифицировать эти узлы и применять особую логику обработки, например, специфическую генерацию HTML-классов или метаданных.

Проверка и фильтрация по пространству имен

При обработке дерева часто возникает необходимость отбирать узлы по их пространству имен:

import { visit } from 'unist-util-visit';

function filterHtmlElements(tree) {
  const elements = [];
  visit(tree, (node) => {
    if (node.type === 'element' && node.namespace === 'html') {
      elements.push(node);
    }
  });
  return elements;
}

Такой подход позволяет разделять обработку Markdown и HTML узлов, не смешивая их логику и предотвращая неожиданные ошибки при генерации или трансформации.

Использование пространств имен в сложных конвейерах

В больших проектах с несколькими плагинами пространства имен позволяют:

Избежать конфликтов между плагинами, которые работают с одинаковыми типами узлов.
Управлять зависимостями между плагинами, например, один плагин может работать только с узлами custom-md, а другой — с html.
Легко дебажить процесс трансформации: в дереве можно визуально различать узлы по их namespace.

import remarkFrontmatter from 'remark-frontmatter';
import remarkCustomNamespace from './remarkCustomNamespace';

const pipeline = unified()
  .use(remarkParse)
  .use(remarkFrontmatter)
  .use(remarkCustomNamespace)
  .use(remarkRehype)
  .use(rehypeStringify);

В этом конвейере фронтматтер обрабатывается в md-пространстве, пользовательские узлы получают собственное пространство, а финальный HTML генерируется уже в html-пространстве.