Конфигурационные файлы

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

Файл конфигурации обычно представлен в формате JavaScript (.js), JSON (.json) или TypeScript (.ts). Наиболее гибкий вариант — JavaScript-файл, поскольку он позволяет динамически формировать конфигурацию и использовать условные конструкции.

// Пример конфигурации для Remark
module.exports = {
  plugins: [
    require('remark-parse'),
    [require('remark-rehype'), { allowDangerousHtml: true }],
    require('rehype-stringify')
  ]
};

В этом примере конфигурация задаёт цепочку плагинов:

  • remark-parse — парсинг Markdown в AST.
  • remark-rehype — преобразование AST Markdown в AST HTML.
  • rehype-stringify — сериализация AST HTML обратно в строку.

Формат плагинов

Плагины в конфигурационном файле могут быть подключены двумя способами:

  1. Простое подключение модуля: используется, когда плагин не требует настройки.
  2. Подключение с параметрами: массив, где первый элемент — модуль, второй — объект настроек.
[require('remark-gfm'), { singleTilde: false }]

Ключевые параметры плагинов варьируются, но обычно включают:

  • options — объект с настройками плагина.
  • settings — специфические для Remark/Rehype опции парсера.
  • allowDangerousHtml — разрешение на обработку “опасного” HTML в потоке.

Подключение внешних конфигураций

Для проектов с большим количеством Markdown и HTML-файлов удобнее выносить общие настройки в отдельные модули. Например:

// common-plugins.js
module.exports = [
  require('remark-parse'),
  require('remark-gfm')
];

// remark.config.js
const commonPlugins = require('./common-plugins');

module.exports = {
  plugins: [
    ...commonPlugins,
    [require('remark-rehype'), { allowDangerousHtml: true }],
    require('rehype-stringify')
  ]
};

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

Использование конфигурационных файлов с API

Remark и Rehype позволяют загружать конфигурацию напрямую через API:

const { unified } = require('unified');
const remarkConfig = require('./remark.config');

const processor = unified()
  .use(remarkConfig.plugins);

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

Настройка порядка плагинов

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

  • remark-parse всегда должен быть первым.
  • Плагины, изменяющие структуру Markdown (например, remark-gfm), подключаются перед конвертацией в HTML.
  • remark-rehype должен идти после всех плагинов, работающих с AST Markdown, и перед rehype-stringify.

Использование .remarkrc и package.json

Remark поддерживает конфигурацию через .remarkrc (JSON или YAML) и раздел remarkConfig в package.json. Пример .remarkrc:

{
  "plugins": [
    "remark-parse",
    ["remark-rehype", { "allowDangerousHtml": true }],
    "rehype-stringify"
  ]
}

Преимущество такого подхода — простая интеграция с CLI-инструментами и отсутствие необходимости создавать отдельный JavaScript-файл. Ограничение — невозможность использовать динамическую логику или условные конструкции.

Расширенные возможности конфигурации

  • Фильтрация по типу файлов: можно применять разные конфигурации к MD и MDX, используя условные конструкции в JS-конфигурации.
  • Интеграция с ESLint и Prettier: Remark и Rehype могут использоваться как часть цепочки линтинга и форматирования.
  • Подключение кастомных плагинов: локальные плагины подключаются аналогично npm-модулям и могут принимать собственные параметры через конфигурацию.
const customPlugin = require('./plugins/my-plugin');

module.exports = {
  plugins: [
    require('remark-parse'),
    [customPlugin, { optionA: true, optionB: 'value' }],
    require('remark-rehype'),
    require('rehype-stringify')
  ]
};

Совместимость конфигураций между Remark и Rehype

Remark и Rehype имеют различную внутреннюю структуру AST (mdast и hast), поэтому плагины Remark не могут работать напрямую с AST Rehype и наоборот. Конфигурационные файлы позволяют явно управлять этапами трансформации и параметрами, обеспечивая совместимость между системами.

Оглавление