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

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

Основные элементы плагина

Любой плагин Markdown-it строится на трёх ключевых компонентах:

Инициализация плагина Плагин — это функция, которая принимает один обязательный аргумент: объект md (инстанс Markdown-it), и опциональные параметры конфигурации. Пример базовой структуры:

function myPlugin(md, options = {}) {
    // Настройка плагина здесь
}

Добавление правил парсинга Markdown-it разделяет парсинг на inline и block.
- Inline-правила обрабатывают текст внутри строки, например, жирный текст, ссылки или эмодзи.
- Block-правила обрабатывают целые блоки, например, заголовки, списки или кодовые блоки.
Для добавления нового блока используется метод md.block.ruler.before или md.block.ruler.after:

md.block.ruler.before('paragraph', 'my_block', function(state, startLine, endLine, silent) {
    // Логика обработки блока
    return true; // возвращает true если правило сработало
});

Для inline-правил применяется md.inline.ruler.before или md.inline.ruler.after:

md.inline.ruler.before('emphasis', 'my_inline', function(state, silent) {
    // Логика обработки inline
    return true;
});

Структура объекта состояния

Парсинг в Markdown-it осуществляется через объект state, который содержит информацию о текущем блоке или inline-элементе:

state.src — исходный текст Markdown.
state.pos и state.posMax — текущая позиция в тексте.
state.tokens — массив токенов, сформированных парсером.

Токен — это объект с ключевыми свойствами:

type — тип токена, например, 'paragraph_open', 'inline', 'strong_open'.
tag — HTML-тег, соответствующий токену ('p', 'strong' и т.д.).
attrs — массив атрибутов для тега.
content — текст внутри токена.
children — массив дочерних токенов для inline-структур.

Добавление токенов и рендеринг

После того как правило парсинга определяет структуру текста, создаются токены. Markdown-it предоставляет конструктор Token:

const Token = require('markdown-it/lib/token');

function addCustomToken(state, content) {
    const token = new Token('my_token', 'span', 0);
    token.content = content;
    state.tokens.push(token);
}

Рендеринг токенов выполняется через renderer rules:

md.renderer.rules.my_token = function(tokens, idx) {
    return `<span class="my-class">${tokens[idx].content}</span>`;
};

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

Опции и конфигурация плагина

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

function myPlugin(md, options) {
    const opts = Object.assign({ enabled: true, className: 'default' }, options);

    if (!opts.enabled) return;

    md.inline.ruler.after('text', 'my_inline', function(state, silent) {
        // обработка с учетом opts.className
    });
}

Такой подход позволяет гибко включать или отключать функциональность без изменения основного кода.

Порядок подключения плагинов

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