Плагин для математических формул

Для работы с математическими формулами в Markdown часто используется плагин markdown-it-katex или markdown-it-math. Эти плагины позволяют интерпретировать выражения, заключённые в $$...$$ для блоков и $...$ для inline-форматирования. Установка осуществляется через npm:

npm install markdown-it markdown-it-katex

Импорт и инициализация плагина в проекте выглядит следующим образом:

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

const md = new MarkdownIt()
    .use(markdownItKatex);

После подключения плагина, все формулы, записанные в формате LaTeX, будут корректно отображаться при генерации HTML. Inline-формулы заключаются в одинарные $, а блочные — в двойные $$.

Настройка отображения формул

Плагин поддерживает различные опции конфигурации для управления рендерингом:

  • throwOnError — выбрасывать ли ошибку при некорректной формуле. Значение по умолчанию: true.
  • errorColor — цвет для отображения ошибок, если throwOnError выключен.
  • macros — пользовательские команды LaTeX.

Пример настройки с пользовательскими макросами:

const md = new MarkdownIt()
    .use(markdownItKatex, {
        throwOnError: false,
        errorColor: 'red',
        macros: {
            "\\RR": "\\mathbb{R}",
            "\\vect": "\\mathbf"
        }
    });

После такой конфигурации можно использовать \RR для обозначения множества действительных чисел, а \vect{v} для жирного вектора v.

Рендеринг inline и блочных формул

Inline-формулы:

Сумма чисел $a + b$ равна $c$.

При обработке Markdown-it с подключённым плагином результат будет HTML-элементом:

Сумма чисел a + b равна c.

Блочные формулы:

$$
\int_0^1 x^2 \, dx
$$

Рендерятся как отдельный блок HTML:


   ...

Расширение возможностей через плагины

Markdown-it поддерживает систему плагинов, что позволяет совместно использовать markdown-it-katex с другими расширениями:

  • markdown-it-emoji для эмодзи;
  • markdown-it-anchor для генерации якорей;
  • markdown-it-footnote для сносок.

Подключение нескольких плагинов:

const markdownItEmoji = require('markdown-it-emoji');

const md = new MarkdownIt()
    .use(markdownItKatex)
    .use(markdownItEmoji);

Важно соблюдать порядок подключения плагинов: рендеринг формул должен происходить до других визуальных преобразований, чтобы не нарушать структуру LaTeX.

Встроенные функции для кастомизации рендеринга

Плагин позволяет переопределять метод рендеринга через renderer.rules:

md.renderer.rules.math_inline = (tokens, idx) => {
    return `${tokens[idx].content}`;
};

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

Поддержка асинхронного рендеринга

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

async function renderMarkdownAsync(mdText) {
    const html = await md.renderAsync(mdText);
    return html;
}

Это обеспечивает совместимость с современными фронтенд-фреймворками, такими как Vue или React, где рендеринг может выполняться асинхронно.

Оптимизация и производительность

При большом количестве формул стоит учитывать:

  • Подключение KaTeX CSS отдельно через для ускорения отображения;
  • Кэширование уже скомпилированных формул;
  • Минимизацию количества вызовов md.render при рендеринге больших документов.

Пример подключения стилей KaTeX:

Это предотвращает повторную генерацию стилей для каждой формулы и ускоряет визуализацию.

Оглавление