Что такое плагины

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

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

Механизм работы плагинов

Плагины подключаются к экземпляру Markdown-it с помощью метода .use(). Этот метод принимает функцию-плагин и опционально объект настроек:

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

md.use(pluginFunction, { option1: true });

Аргументы функции-плагина:

  1. md — объект экземпляра Markdown-it. Через него доступен API для добавления правил и модификации рендеринга.
  2. options — объект настроек, переданных при подключении плагина.

Плагин может регистрировать новые правила, изменять существующие, добавлять собственные блоки (block rules) и инлайн-правила (inline rules).

Типы плагинов

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

md.use(require('markdown-it-attrs')); // добавление атрибутов к элементам

2. Плагины для рендеринга Модифицируют итоговый HTML или добавляют обработку нестандартных тегов. Например, плагин для генерации таблицы содержания или собственных HTML-компонентов.

md.use(require('markdown-it-anchor')); // добавление якорей к заголовкам

3. Плагины для фильтрации и постобработки Позволяют анализировать или трансформировать уже сгенерированный AST (Abstract Syntax Tree) перед выводом HTML. Например, можно автоматически удалять пустые теги или преобразовывать определённые ссылки.

Структура плагина

Типичный плагин Markdown-it состоит из следующих частей:

  1. Регистрация правил блоков и инлайновых элементов

    • md.block.ruler.before() или md.block.ruler.after() для блоков.
    • md.inline.ruler.before() или md.inline.ruler.after() для инлайновых элементов.

  2. Определение функций рендеринга Каждому типу токена можно назначить рендерер через md.renderer.rules[tokenName].

md.renderer.rules.custom_token = function(tokens, idx) {
  return `<span class="custom">${tokens[idx].content}</span>`;
};
  1. Работа с токенами Токены — это единицы AST, содержащие тип, содержимое, уровень вложенности и атрибуты. Плагин может создавать новые токены, изменять существующие или удалять ненужные.

Примеры использования

Добавление кастомного блока «spoiler»

function spoilerPlugin(md) {
  md.block.ruler.before('paragraph', 'spoiler', function(state, startLine, endLine, silent) {
    const pos = state.bMarks[startLine] + state.tShift[startLine];
    const max = state.eMarks[startLine];
    const lineText = state.src.slice(pos, max);

    if (!lineText.startsWith(':::spoiler')) return false;
    if (silent) return true;

    let nextLine = startLine + 1;
    while (nextLine < endLine && !state.src.slice(state.bMarks[nextLine] + state.tShift[nextLine], state.eMarks[nextLine]).startsWith(':::')) {
      nextLine++;
    }

    const token = state.push('spoiler_open', 'div', 1);
    token.attrs = [['class', 'spoiler']];
    state.md.block.tokenize(state, startLine + 1, nextLine);

    state.push('spoiler_close', 'div', -1);
    state.line = nextLine + 1;
    return true;
  });
}

md.use(spoilerPlugin);

Результат: текст между :::spoiler и ::: оборачивается в <div class="spoiler">.

Принципы разработки плагинов

  • Согласованность с AST: любые изменения токенов должны учитывать вложенность и корректное завершение блоков.
  • Изоляция: плагин не должен ломать стандартные правила Markdown.
  • Конфигурируемость: все пользовательские параметры лучше передавать через объект options.
  • Производительность: избегать глубоких циклов по токенам, особенно для больших документов.

Встроенные плагины Markdown-it

Библиотека поставляется с рядом популярных официальных плагинов:

  • markdown-it-emoji — поддержка смайликов :smile:.
  • markdown-it-footnote — обработка сносок.
  • markdown-it-deflist — создание определённых списков.
  • markdown-it-sub и markdown-it-sup — индексы и верхние индексы.

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

Итоговое понимание

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

Оглавление