Класс MarkdownIt

Класс MarkdownIt является ядром одноимённой библиотеки для парсинга Markdown в JavaScript. Он предоставляет мощный и гибкий интерфейс для преобразования текста в HTML с возможностью расширения функциональности через плагины и собственные правила.

Создание экземпляра:

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

По умолчанию экземпляр MarkdownIt поддерживает стандартный синтаксис Markdown. В конструктор можно передавать объект с настройками, позволяющими управлять обработкой текста.

const md = new MarkdownIt({
  html: true,          // разрешает HTML в Markdown
  linkify: true,       // автоматически превращает URL в ссылки
  typographer: true    // включает типографские преобразования
});

Основные методы класса

render(src, env)

Метод render принимает строку src с Markdown-текстом и возвращает HTML:

const result = md.render('# Заголовок\n\nТекст абзаца.');
console.log(result);

Параметр env позволяет передавать дополнительные данные в процесс рендеринга. Он используется для передачи пользовательской информации в плагины или обработчики.

renderInline(src, env)

Метод для обработки только inline-элементов, таких как ссылки, выделение, эмоджи и др.:

const inlineResult = md.renderInline('Текст с **жирным** выделением.');
console.log(inlineResult);

use(plugin, options)

Позволяет подключать плагины для расширения функционала:

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

md.use(markdownItFootnote);

Плагины могут изменять правила токенизации, добавлять новые синтаксические конструкции и изменять HTML-рендеринг.

Настройки класса MarkdownIt

Ключевые опции при создании экземпляра:

  • html: true/false — разрешение HTML-тегов.
  • xhtmlOut: true/false — использовать самозакрывающиеся теги.
  • breaks: true/false — перевод строки как <br>.
  • linkify: true/false — автоматическая конвертация URL в ссылки.
  • typographer: true/false — типографские замены (например, кавычки и тире).

Пример комбинирования настроек:

const md = new MarkdownIt({
  html: true,
  breaks: true,
  linkify: true,
  typographer: true
});

Работа с токенами

MarkdownIt сначала токенизирует входной текст, а затем преобразует токены в HTML. Токен — это объект с полями:

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

Пример получения токенов:

const tokens = md.parse('Текст **жирный**', {});
console.log(tokens);

Это позволяет создавать собственные правила рендеринга, изменять структуру HTML или анализировать Markdown.

Настройка рендеринга

MarkdownIt использует Render Rules — функции, которые определяют, как токены преобразуются в HTML. Рендеринг можно изменить глобально:

md.renderer.rules.strong_open = function(tokens, idx) {
  return '<b class="custom-bold">';
};
md.renderer.rules.strong_close = function() {
  return '</b>';
};

Также можно добавлять свои правила для нестандартных токенов, создаваемых плагинами.

Плагины и расширяемость

Плагины могут:

  • Добавлять новые синтаксические конструкции.
  • Модифицировать существующие правила токенизации.
  • Вставлять пользовательские HTML-шаблоны.

Пример плагина для вставки даты:

function datePlugin(md) {
  md.inline.ruler.after('text', 'date', function(state, silent) {
    const match = state.src.slice(state.pos).match(/\{\{date\}\}/);
    if (!match) return false;
    if (!silent) {
      const token = state.push('html_inline', '', 0);
      token.content = new Date().toLocaleDateString();
    }
    state.pos += match[0].length;
    return true;
  });
}

md.use(datePlugin);

Работа с окружением (env)

Параметр env в методах render и parse позволяет передавать контекст:

const env = { user: 'Alice' };
const html = md.render('Привет, {{user}}', env);

Плагины и кастомные правила могут использовать данные из env для динамического рендеринга.

Поддержка CommonMark и расширений

MarkdownIt ориентирован на CommonMark, но поддерживает расширения:

  • Footnotes
  • Abbreviations
  • Task lists
  • Emoji

Подключение расширений через плагины обеспечивает гибкость и соответствие различным стандартам Markdown.

Итоговая архитектура

  • Парсер (Parser): преобразует Markdown в токены.
  • Рендерер (Renderer): превращает токены в HTML.
  • Плагины (Plugins): добавляют новые синтаксические конструкции или изменяют существующие.
  • Настройки (Options): контролируют обработку HTML, типографику, ссылки и разрывы строк.
  • Окружение (Env): хранит контекст для динамического рендеринга.

MarkdownIt сочетает высокую скорость и расширяемость, что делает его универсальным инструментом для работы с Markdown в JavaScript.

Оглавление