remark-math: математические формулы

remark-math — это плагин для экосистемы Remark, который обеспечивает поддержку математических формул в Markdown-документах. Он позволяет распознавать и обрабатывать выражения в формате LaTeX, включая как встроенные формулы, так и блоки с отдельными выражениями. Для корректного рендеринга формул часто используется связка с rehype-katex, обеспечивающая визуализацию через библиотеку KaTeX.

Установка и подключение

Для работы с remark-math необходимо установить сам пакет и сопутствующие зависимости:

npm install remark remark-math rehype rehype-katex unified

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

import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkMath from 'remark-math';
import remarkRehype from 'remark-rehype';
import rehypeStringify from 'rehype-stringify';
import rehypeKatex from 'rehype-katex';
import fs from 'fs';

const markdown = fs.readFileSync('example.md', 'utf-8');

const processor = unified()
  .use(remarkParse)
  .use(remarkMath)
  .use(remarkRehype)
  .use(rehypeKatex)
  .use(rehypeStringify);

const html = processor.processSync(markdown).toString();
console.log(html);

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

  • remarkParse парсит исходный Markdown.
  • remarkMath выделяет математические выражения.
  • remarkRehype конвертирует дерево Markdown (MDAST) в дерево HTML (HAST).
  • rehypeKatex преобразует LaTeX-формулы в HTML с CSS-стилями.
  • rehypeStringify генерирует финальный HTML-код.

Синтаксис формул

remark-math поддерживает два типа математических выражений:

  1. Inline-формулы — заключаются в одинарные знаки доллара $...$:
Формула Эйлера: $e^{i\pi} + 1 = 0$
  1. Блочные формулы — заключаются в двойные знаки доллара $$...$$:
$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

Inline-формулы встроены в текст, а блочные формулы занимают отдельный блок и выравниваются по центру. remark-math автоматически определяет эти конструкции и добавляет соответствующие узлы в дерево MDAST:

  • inlineMath для встроенных формул.
  • math для блочных формул.

Структура узлов MDAST

После обработки Markdown с remark-math дерево MDAST будет содержать специальные узлы:

{
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "type": "text",
          "value": "Формула Эйлера: "
        },
        {
          "type": "inlineMath",
          "value": "e^{i\\pi} + 1 = 0"
        }
      ]
    },
    {
      "type": "math",
      "value": "\\int_0^\\infty e^{-x^2} dx = \\frac{\\sqrt{\\pi}}{2}"
    }
  ]
}

inlineMath и math содержат поле value, в котором хранится исходный LaTeX-код. Эти узлы впоследствии используются rehype-katex для рендеринга в HTML.

Настройка KaTeX

rehype-katex позволяет управлять визуализацией формул:

.use(rehypeKatex, { 
  throwOnError: false, 
  errorColor: "#cc0000"
});
  • throwOnError: false предотвращает падение сборки при ошибках в LaTeX.
  • errorColor задает цвет подсветки ошибок.

Можно подключать собственные CSS-стили для KaTeX, чтобы формулы соответствовали дизайну страницы:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.4/dist/katex.min.css">

Интеграция с Remark-плагинами

remark-math хорошо сочетается с другими плагинами Remark, например:

  • remark-gfm — поддержка таблиц и расширенного синтаксиса Markdown.
  • remark-frontmatter — обработка YAML-заголовков документа.
  • remark-toc — генерация оглавления.

Важно соблюдать порядок подключения: remark-math должен идти после remark-parse и перед remark-rehype, чтобы математические узлы корректно передавались в HTML.

Примеры сложных выражений

  1. Системы уравнений в блоке:
$$
\begin{cases}
x + y = 2 \\
x - y = 0
\end{cases}
$$
  1. Дроби, индексы и корни:
$$
f(x) = \frac{1}{\sqrt{2\pi}} e^{-x^2/2}
$$
  1. Комбинация inline и блочного формата:
Решение уравнения $ax^2 + bx + c = 0$ может быть записано как
$$
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

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

Особенности использования

  • Автозамена спецсимволов: LaTeX-символы внутри формул не экранируются дополнительно.
  • Ошибки синтаксиса: некорректные выражения выделяются как ошибки при рендеринге KaTeX.
  • Совместимость с Markdown: текст вне формул не затрагивается, что позволяет безопасно сочетать обычный Markdown и математические блоки.
  • Поддержка экспорта: можно конвертировать Markdown с формулами в HTML, React-компоненты или PDF через соответствующие сборщики.

Практические советы

  • Для больших документов рекомендуется подключать rehype-katex один раз на уровне сборщика, чтобы избежать дублирования стилей.
  • Inline-формулы лучше использовать для простых выражений, а сложные вычисления — в блочных формулах.
  • Всегда проверять LaTeX-синтаксис перед публикацией, чтобы избежать некорректного рендеринга.
  • Для динамического контента в React или Vue можно оборачивать результат в компонент, обеспечивающий безопасное внедрение HTML с формулами.

remark-math вместе с rehype-katex образует мощный инструмент для работы с математикой в Markdown, позволяя создавать аккуратные и визуально корректные формулы без необходимости ручного HTML.

Оглавление