Включение и отключение правил

Markdown-it предоставляет гибкий механизм управления правилами синтаксиса, что позволяет настраивать обработку Markdown на уровне токенов и парсеров. Работа с правилами осуществляется через парсерные цепочки (parser rules) и рендереры (renderer rules), что позволяет включать, отключать или переопределять отдельные элементы разметки.

Парсерные правила

Парсерные правила — это функции, которые разбирают исходный текст и создают токены. Каждое правило отвечает за конкретный синтаксический элемент: заголовки, списки, ссылки, жирный текст и т.д.

  • Доступ к правилам осуществляется через объект md.core.ruler для глобальных правил, md.block.ruler для блочных элементов и md.inline.ruler для встроенных.
  • Каждое правило имеет имя, которое используется для включения, отключения или замены.
const MarkdownIt = require('markdown-it');
const md = new MarkdownIt();

// Отключение правила выделения жирного текста
md.inline.ruler.disable('strong');

// Включение правила обратно
md.inline.ruler.enable('strong');

Методы disable и enable принимают имя правила или массив имён. Отключение правила полностью убирает его из процесса токенизации, что позволяет исключить ненужные элементы разметки без изменения исходного кода Markdown-it.

Переопределение правил

Для изменения поведения стандартного правила используется метод md.renderer.rules[name]. Он позволяет задать собственную функцию рендеринга для определённого типа токена:

// Переопределяем рендеринг заголовков
md.renderer.rules.heading_open = (tokens, idx, options, env, self) => {
  const level = tokens[idx].tag;
  return `<${level} class="custom-heading">`;
};

В этом примере стандартный HTML для заголовков заменяется на элемент с дополнительным классом. При этом токены продолжают создаваться стандартным парсером, изменяется только процесс рендеринга.

Последовательность правил

Markdown-it обрабатывает текст в несколько этапов:

  1. Ядро (core) — последовательность правил, выполняемых над всем документом.
  2. Блочные правила (block) — разбор больших структур: параграфы, списки, цитаты.
  3. Встроенные правила (inline) — обработка текста внутри блочных элементов: ссылки, выделение, коды.

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

Пример комплексной настройки

const md = new MarkdownIt();

// Отключаем ссылки и изображения
md.inline.ruler.disable(['link', 'image']);

// Переопределяем рендеринг кода
md.renderer.rules.code_inline = (tokens, idx) => {
  return `<code class="inline-code">${tokens[idx].content}</code>`;
};

// Добавляем пользовательское блочное правило
md.block.ruler.before('paragraph', 'alert_block', (state, startLine, endLine, silent) => {
  const line = state.getLines(startLine, startLine + 1, 0, false);
  if (!line.startsWith('!!!')) return false;
  
  if (!silent) {
    const token = state.push('alert_open', 'div', 1);
    token.attrs = [['class', 'alert']];
    state.push('inline', '', 0).content = line.slice(3).trim();
    state.push('alert_close', 'div', -1);
  }
  
  state.line = startLine + 1;
  return true;
});

В этом примере:

  • Отключены стандартные правила ссылок и изображений.
  • Переопределён рендеринг встроенного кода.
  • Добавлено пользовательское блочное правило alert_block, создающее элемент <div class="alert">.

Практические рекомендации

  • Отключение правил: использовать для исключения нежелательных элементов или предотвращения конфликтов с кастомными правилами.
  • Включение правил: полезно после временной деактивации, особенно при динамической настройке Markdown.
  • Переопределение рендереров: безопасный способ изменить вывод HTML без вмешательства в парсер.
  • Порядок правил: при добавлении пользовательских правил учитывать их позицию относительно стандартных (before или after других правил).

Гибкость управления правилами позволяет создавать Markdown-парсеры под специфические задачи: от упрощённого синтаксиса до расширенного с кастомными блоками и стилями рендеринга.

Оглавление