Встроенные правила

Markdown-it — это высокопроизводительный парсер Markdown для JavaScript, разработанный с модульной архитектурой, где встроенные правила играют ключевую роль. Правила определяют, как исходный текст интерпретируется и преобразуется в токены, которые затем рендерятся в HTML. Встроенные правила делятся на несколько категорий: блоковые, строчные и специальные правила для inline-синтаксиса.

Блоковые правила (block rules)

Блоковые правила отвечают за обработку элементов Markdown, которые занимают отдельные строки или блоки текста. Основные блоковые элементы включают заголовки, списки, блоки кода и цитаты.

Заголовки

Markdown-it поддерживает два типа заголовков:

  1. ATX-заголовки — создаются с помощью символа #.
  2. Setext-заголовки — создаются при помощи подчеркивания символами = или -.

Парсер проходит текст построчно и применяет правило heading для распознавания заголовка, создавая токены типа heading_open, inline, heading_close. Каждому заголовку присваивается уровень (h1, h2 и т.д.), что позволяет корректно рендерить HTML.

Списки

Markdown-it различает упорядоченные и неупорядоченные списки. Для их обработки используется правило list, которое анализирует маркеры (*, -, + для unordered, цифры с точкой для ordered). В процессе парсинга формируются токены:

  • bullet_list_open / ordered_list_open
  • list_item_open
  • inline
  • list_item_close
  • bullet_list_close / ordered_list_close

Каждый элемент списка проходит вложенный inline-парсинг, что позволяет внутри списка использовать ссылки, выделения и другие inline-элементы.

Блоки кода

Существуют два типа блоков кода:

  1. Indented code blocks — создаются при помощи отступа в 4 пробела или табуляции.
  2. Fenced code blocks — создаются с использованием тройных обратных кавычек ````или тильд~~~`.

Markdown-it создает токены fence для fenced code blocks с параметрами content (содержимое блока) и info (опциональный язык программирования для подсветки синтаксиса).

Цитаты

Правила для блоков цитат анализируют строки, начинающиеся с >. Создаются токены blockquote_open, inline, blockquote_close. Все содержимое цитаты проходит дальнейший парсинг для inline-элементов.

Строчные правила (inline rules)

Inline правила отвечают за обработку текста внутри блоков. Основные inline-элементы включают ссылки, изображения, выделения, код и автоматические URL.

Выделения

Markdown-it поддерживает:

  • Жирный текст — двойное обрамление ** или __
  • Курсив — одинарное обрамление * или _
  • Зачеркнутый текст — двойное тильда ~~

Токены для этих элементов: strong_open, em_open, s_open с соответствующими *_close.

Ссылки и изображения

Ссылки и изображения создаются через правила link и image. Синтаксис Markdown:

[текст ссылки](URL "title")
![альт-текст](URL "title")

Токены для ссылок:

  • link_open с атрибутами href и title
  • inline для текста ссылки
  • link_close

Для изображений генерируется токен image с атрибутами src, alt и title.

Код внутри строки

Inline-код создается при помощи одиночных обратных кавычек `. Markdown-it создает токен code с содержимым внутри кавычек.

Автоматические ссылки

Markdown-it поддерживает автоматическое преобразование URL и email-адресов в ссылки через правило autolink. Например, http://example.com автоматически преобразуется в <a href="/goto/?url=http://example.com" target="_blank">http://example.com</a>.

Специальные встроенные правила

Правила для таблиц

Markdown-it включает поддержку таблиц через отдельный модуль markdown-it-table. Таблицы парсятся по строкам с разделителями | и создают токены table_open, thead_open, tr_open, td_open, inline и соответствующие закрывающие токены.

Правила для горизонтальных линий

Горизонтальная линия определяется как строка, содержащая три и более символов *, - или _. Генерируется токен hr.

Экранирование

Markdown-it использует правило escape для обработки обратного слэша \, что позволяет вставлять спецсимволы Markdown без их интерпретации.

Взаимодействие правил

Markdown-it строит дерево токенов, применяя блоковые правила сначала, а затем inline-правила к каждому блоку. Это позволяет комбинировать элементы, например:

  • Списки с выделенным текстом
  • Заголовки с [ссылками](URL)
  • Блоки кода внутри цитат

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

Настройка и отключение правил

Markdown-it позволяет управлять встроенными правилами через методы enable(), disable() и настройку rules. Пример отключения HTML-тегов:

const md = require('markdown-it')({
  html: false
});
md.disable(['html_block', 'html_inline']);

Также можно подключать пользовательские правила с помощью md.core.ruler.push() или md.inline.ruler.before(), что обеспечивает гибкость и расширяемость парсера без модификации исходного кода встроенных правил.

Итоговая структура токенов

Каждое правило Markdown-it преобразует исходный текст в последовательность токенов с полями:

  • type — тип токена (например, paragraph_open)
  • tag — HTML-тег для рендеринга
  • attrs — массив атрибутов
  • content — текст для inline-токенов
  • children — вложенные токены для inline-парсинга
  • level — глубина вложенности

Эта структура позволяет не только рендерить HTML, но и создавать альтернативные представления, например, JSON-дерево или AST для дальнейшей обработки.

Оглавление