Настройка опций трансформации

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

Конфигурация Remark

Remark использует объект опций, который передается в метод remark() или при инициализации через unified(). Основные параметры:

  • extensions – массив расширений для парсинга Markdown. Позволяет включать поддержку нестандартных синтаксисов.

  • plugins – массив плагинов, которые применяются последовательно. Каждый плагин может принимать свои опции.

  • settings – объект, определяющий общие настройки работы парсера и компилятора, например:

    • position: указывает, сохранять ли позицию узлов в исходном тексте.
    • gfm: включение расширений GitHub Flavored Markdown.
    • commonmark: строгий режим CommonMark.

Пример настройки Remark с плагинами:

import { remark } from 'remark';
import remarkGfm from 'remark-gfm';
import remarkSlug from 'remark-slug';

const processor = remark()
  .use(remarkGfm)
  .use(remarkSlug, { prefix: 'section-' })
  .processSync('# Заголовок');

Здесь remarkGfm расширяет синтаксис Markdown, а remarkSlug добавляет идентификаторы к заголовкам.

Настройка Rehype

Rehype работает аналогично, но с фокусом на HTML AST. Основные опции:

  • settings – объект глобальных настроек. Часто используемые параметры:

    • fragment: если true, процессор будет работать с HTML-фрагментами, без обёртки в <html>.
    • space: управление пробелами между текстовыми узлами.

  • plugins – массив плагинов для трансформации HTML-дерева. Плагины могут модифицировать узлы, добавлять атрибуты или удалять элементы.

Пример использования Rehype с плагином:

import { rehype } from 'rehype';
import rehypeFormat from 'rehype-format';
import rehypeSanitize from 'rehype-sanitize';

const processor = rehype()
  .data('settings', { fragment: true })
  .use(rehypeFormat)
  .use(rehypeSanitize);

const result = processor.processSync('<div><strong>Текст</strong></div>');

rehypeFormat форматирует HTML с отступами, а rehypeSanitize очищает код от потенциально опасного содержимого.

Управление последовательностью плагинов

Порядок подключения плагинов влияет на результат трансформации. Плагины применяются последовательно, и изменения, внесённые одним плагином, видны следующим. Для сложных цепочек важно правильно распределять плагины:

  1. Парсинг исходного текста (remark-parse).
  2. Добавление или модификация узлов (например, remark-slug, remark-autolink-headings).
  3. Финальная компиляция (remark-stringify или rehype-stringify).

Передача опций в плагины

Большинство плагинов принимает объект с параметрами. Например, remark-autolink-headings позволяет настроить символ ссылки, позицию и классы:

import remarkAutolinkHeadings from 'remark-autolink-headings';

remark()
  .use(remarkAutolinkHeadings, {
    beh * avior: 'prepend',
    content: { type: 'text', value: '§' },
  });

Настройка через объект гарантирует гибкость и позволяет использовать один плагин в разных частях проекта с разными параметрами.

Глобальные и локальные опции

  • Глобальные опции задаются через .data('settings', {...}) и влияют на все последующие плагины.
  • Локальные опции передаются непосредственно в плагин при подключении через .use(plugin, options).

Гибридное использование позволяет контролировать как общие параметры работы процессора, так и поведение отдельных плагинов.

Прямое изменение AST

Для тонкой настройки трансформаций можно использовать собственные функции-обработчики узлов:

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

function customPlugin() {
  return (tree) => {
    visit(tree, 'heading', (node) => {
      node.data = node.data || {};
      node.data.customId = `heading-${node.position.start.line}`;
    });
  };
}

remark().use(customPlugin).processSync('# Тест');

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

Рекомендации по оптимизации

  • Использовать processSync для быстрых операций, process для асинхронных.
  • Минимизировать количество плагинов, которые изменяют однотипные узлы, чтобы избежать лишних проходов по дереву.
  • Явно указывать settings при работе с HTML-фрагментами для Rehype, чтобы избежать добавления лишних тегов <html> и <body>.

Настройка опций трансформации Remark и Rehype обеспечивает контроль над каждой стадией обработки Markdown и HTML, от парсинга до финального вывода, позволяя создавать гибкие, расширяемые и безопасные системы генерации контента.

Оглавление