Изменения в API

Библиотека Markdown-it прошла через несколько значительных обновлений, которые затронули как внутреннюю архитектуру, так и внешний API. Понимание этих изменений критически важно для разработчиков, которые используют Markdown-it в проектах на JavaScript, особенно при миграции с более старых версий.

Инициализация и настройка

В новых версиях Markdown-it подход к созданию экземпляра стал более гибким. Ранее использовались простые конструкторы с объектом опций:

const md = require('markdown-it')({
  html: true,
  linkify: true,
  typographer: false
});

Сейчас же введена поддержка цепочек конфигурации, что позволяет настраивать поведение плагинов и рендереров отдельно:

const MarkdownIt = require('markdown-it');

const md = new MarkdownIt()
  .enable(['emphasis', 'link'])
  .disable(['html_block'])
  .set({ typographer: true });

Ключевые изменения:

  • Методы enable и disable позволяют тонко управлять подключаемыми правилами.
  • Метод set заменяет прямую передачу опций в конструктор, что упрощает изменение конфигурации на лету.
  • Некоторые старые опции стали устаревшими или изменили имя (например, quotes теперь задаются через set({ quotes: '«»‘’' })).

Работа с плагинами

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

const footnote = require('markdown-it-footnote');

md.use(footnote)
  .use(require('markdown-it-anchor'), { permalink: true });

Особенности нового API плагинов:

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

Изменения в системе токенов

Markdown-it использует двухступенчатую модель обработки: токенизация → рендеринг. В новых версиях структура токенов была уточнена:

{
  type: 'paragraph_open',
  tag: 'p',
  attrs: null,
  map: [0, 1],
  nesting: 1,
  level: 0,
  children: null,
  content: '',
  markup: '',
  info: ''
}

Важные моменты:

  • map теперь всегда содержит индексы начала и конца строки исходного текста.
  • level и nesting позволяют точно отслеживать вложенность блоков.
  • children используются только для инлайновых элементов, что разграничивает обработку блоков и строчного содержимого.
  • Рендереры были переписаны для более предсказуемого поведения при кастомизации.

Рендереры и кастомизация вывода

Ранее для изменения рендеринга достаточно было переопределять отдельные методы рендерера. Сейчас структура более модульная:

md.renderer.rules.heading_open = function(tokens, idx, options, env, self) {
  return `<h${tokens[idx].tag}>`;
};

md.renderer.rules.paragraph_close = function(tokens, idx) {
  return '</p>\n';
};

Нововведения:

  • Все правила рендерера теперь доступны через md.renderer.rules.
  • Поддержка контекста через объект env позволяет передавать пользовательские данные в процессе рендеринга.
  • Встроенные правила можно комбинировать с пользовательскими, используя self.renderToken(tokens, idx, options) внутри кастомного метода.

Обработка ссылок и изображений

Система ссылок (link) и изображений (image) получила более строгую валидацию. Теперь при парсинге учитываются следующие моменты:

  • Абсолютные и относительные URL: автоматически проверяются на корректность.
  • Ссылки на footnotes: обрабатываются через отдельный токен footnote_ref.
  • Атрибуты title и alt: теперь полностью поддерживаются и передаются в рендерер.
md.use(require('markdown-it-attrs'));

const result = md.render('[example](https://site.com "Title"){.class}');

Поддержка новых синтаксических возможностей

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

  • Deflist — определение списков с ключ-значение.
  • Abbr — сокращения с расшифровкой.
  • Sub/Sup — подстрочные и надстрочные элементы.
  • Task lists — интерактивные списки задач с чекбоксами.

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

Совместимость и миграция

При обновлении с версий до 13.x на 14.x+ необходимо учитывать:

  1. Старые опции конструктора могут быть удалены.
  2. Методы enable/disable заменяют прямую работу с массивом правил.
  3. Плагины старого формата могут не поддерживать новый env и структуру токенов.
  4. Кастомные рендереры должны использовать tokens[idx] и self.renderToken для корректной работы.

Эти изменения делают Markdown-it более гибким, модульным и предсказуемым, особенно в больших проектах с кастомными плагинами и рендерингом. Понимание новых методов работы с токенами, рендерерами и плагинами позволяет строить сложные парсеры Markdown без необходимости модифицировать ядро библиотеки.

Оглавление