Автоматические замены

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

Основные концепции

Автоматические замены в Markdown-it реализуются через систему core rules и inline rules, которые проходят по тексту и ищут совпадения с определёнными паттернами. Эти правила можно разделить на:

  1. Core rules — работают на уровне всего документа, позволяют изменять блоки и структуру документа.
  2. Inline rules — работают внутри текста, применяются к символам, словам и последовательностям внутри абзацев.

Для автоматических замен чаще всего используются inline правила, так как они позволяют заменять символы на лету при рендеринге.

Настройка автоматических замен

Markdown-it поставляется с базовым набором замен, которые можно включать или отключать при инициализации:

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

const md = new MarkdownIt({
  typographer: true // включает автоматические типографские замены
});

Опция typographer: true активирует следующие замены:

  • -- → длинное тире (—)
  • ... → многоточие (…)
  • " " → «елочки» в кавычках (“”)
  • ' ' → апострофы и одинарные кавычки (‘’)

Эти преобразования работают автоматически на всех блоках текста, где разрешён inline Markdown.

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

Для более тонкой настройки замен можно использовать объект md.core.ruler или md.inline.ruler:

md.inline.ruler.before('emphasis', 'custom_replace', function(state) {
  const src = state.src;
  state.src = src.replace(/\(c\)/gi, '©');
  return true;
});

Здесь:

  • before('emphasis', ...) указывает, что правило сработает перед обработкой курсивов.
  • Функция получает объект state, содержащий текст документа.
  • Метод replace позволяет внедрять собственные правила замены.

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

Поддержка эмодзи

Markdown-it имеет отдельный плагин для эмодзи — markdown-it-emoji, который интегрируется через стандартные правила inline:

const md = require('markdown-it')().use(require('markdown-it-emoji'));

console.log(md.render('I :heart: Markdown-it!'));
// Выведет: I ❤️ Markdown-it!

Плагин использует словарь эмодзи и автоматически заменяет обозначения вида :name: на соответствующий символ. Также можно расширять словарь или переопределять существующие замены.

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

Пользовательские замены с регулярными выражениями

Для сложных сценариев удобно использовать регулярные выражения. Например, чтобы автоматически заменять даты в формате YYYY-MM-DD на <time>:

md.inline.ruler.after('text', 'date_replace', function(state) {
  state.tokens.forEach(token => {
    if (token.type === 'text') {
      token.content = token.content.replace(
        /\b(\d{4}-\d{2}-\d{2})\b/g,
        '<time>$1</time>'
      );
    }
  });
  return true;
});

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

Контроль порядка применения правил

Markdown-it выполняет inline правила строго в том порядке, в котором они зарегистрированы. Это важно при работе с автоматическими заменами:

  • Сначала выполняются более общие правила.
  • Затем — специфические пользовательские замены.
  • Конфликты между правилами решаются порядком их регистрации: правило, зарегистрированное позже, может изменять результат предыдущего.

Использование методов before и after позволяет гибко контролировать последовательность:

md.inline.ruler.before('emphasis', 'custom_quotes', customQuotesRule);

Ограничение автоматических замен

В некоторых случаях автоматические замены могут быть нежелательными. Для этого можно:

  1. Отключить типографские правила при инициализации:
const md = new MarkdownIt({ typographer: false });

  1. Исключить замену внутри определённых блоков с помощью специальных inline правил, проверяя state.pos и token.type.

  2. Комбинировать Markdown-it с плагинами, которые фильтруют замену в определённых областях, например внутри кода или ссылок.

Вывод

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

  • типографские улучшения,
  • эмодзи,
  • кастомные сокращения,
  • динамические HTML-преобразования.

Правильное использование core и inline правил вместе с плагинами позволяет создавать мощные и безопасные преобразования текста без вмешательства в основную структуру Markdown.

Оглавление