Ключевые концепции

unifast компилирует Markdown через многоступенчатый конвейер. Понимание этих этапов помогает настраивать компилятор и выбирать подходящие плагины.

Конвейер компиляции

Входной текст
  → Парсинг (Markdown или MDX)
  → IR0: MdAst (структура Markdown)
  → Нормализация + встроенные проходы MdAst
  → Понижение в IR1: HAst (структура HTML)
  → Проходы HAst (sanitize, highlight и т. д.)
  → Эмиссия (строка HTML)

Каждая стадия преобразует документ через промежуточное представление (IR).

Промежуточные представления

Парсер создаёт MdAst, который затем понижается в HAst для эмиссии HTML. Входные данные MDX дополнительно порождают узлы JsAst для вывода JavaScript.

Проходы

Проходы — это преобразования, применяемые к AST на определённых фазах. В unifast есть встроенные проходы для типичных задач:

Проходы MdAst (до понижения в HTML):

• Normalize — согласованная структура для последующих проходов

• Slug — генерация ID заголовков из текстового содержимого

• TOC — извлечение оглавления из заголовков

• Definition Resolution — разрешение ссылочных определений для ссылок и изображений

Проходы HAst (после понижения в HTML):

• Sanitize — удаление запрещённых HTML-элементов и атрибутов

• Highlight — применение подсветки синтаксиса к блокам кода

• Cleanup — удаление ненужных узлов и пробелов

Проходы упорядочены по фазам — вам не нужно беспокоиться о порядке выполнения.

Плагины

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

import { compile, gfm, sanitize } from "@unifast/node";

const result = compile(source, {
  plugins: [gfm(), sanitize()],
});

Каждый плагин возвращает объект конфигурации, который сливается с параметрами компиляции до запуска ядра на Rust. Это сохраняет весь горячий путь исключительно в нативном коде.

Форматы вывода

Компилятор поддерживает несколько форматов вывода через параметр outputKind:

Диагностика

Компилятор сообщает о проблемах через массив diagnostics в результате. Каждая диагностика содержит уровень серьёзности, сообщение и необязательный диапазон в исходном коде для точного указания местоположения ошибки.

const result = compile(source);

for (const d of result.diagnostics) {
  console.warn(`[${d.level}] ${d.message}`);
}