Использование в Node.js

Для работы с Markdown-it в Node.js необходимо сначала установить библиотеку через npm:

npm install markdown-it

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

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

Здесь создаётся экземпляр парсера md, который будет использоваться для преобразования Markdown-текста в HTML.

Преобразование Markdown в HTML

Основная функция Markdown-it — конвертация Markdown в HTML. Для этого используется метод render:

const markdownText = `
# Заголовок первого уровня

Это пример текста с **жирным** и *курсивом*.
`;

const result = md.render(markdownText);
console.log(result);

Результатом будет HTML:

<h1>Заголовок первого уровня</h1>
<p>Это пример текста с <strong>жирным</strong> и <em>курсивом</em>.</p>

Метод render принимает на вход строку Markdown и возвращает строку HTML. Для обработки отдельных строк можно использовать renderInline, который не создаёт контейнерный <p>:

const inlineResult = md.renderInline("Пример **жирного** текста");
console.log(inlineResult); // Пример <strong>жирного</strong> текста

Настройка парсера

Markdown-it поддерживает гибкую настройку через объект конфигурации при создании экземпляра:

const md = new MarkdownIt({
  html: true,          // Разрешить HTML-теги в тексте
  xhtmlOut: false,     // Использовать закрывающие слеши в теге <br />
  breaks: true,        // Перевод строк с помощью одного переноса строки
  langPrefix: 'lang-', // Префикс для блоков кода
  linkify: true,       // Автоматическая конвертация URL в ссылки
  typographer: true    // Включение типографики (кавычки, тире)
});

Ключевые моменты настроек:

  • html: если true, HTML в исходном Markdown будет оставлен без изменений.
  • breaks: заменяет обычный перенос строки на <br>.
  • linkify: автоматически превращает URL в <a> ссылки без использования Markdown-синтаксиса.
  • typographer: применяет замены вроде «—» → «—», "..." → «…» и прочие правила типографики.

Работа с плагинами

Markdown-it поддерживает систему плагинов, которые расширяют стандартные возможности парсера.

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

const text = "Текст с сноской[^1]\n\n[^1]: Текст сноски";
console.log(md.render(text));

Результат автоматически обработает сноску и сгенерирует соответствующую HTML-разметку.

Подключение плагина осуществляется через метод use. Любой плагин принимает дополнительные параметры для настройки.

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

Markdown-it позволяет переопределять рендеринг отдельных типов токенов через объект renderer.rules. Например, можно изменить поведение заголовков:

md.renderer.rules.heading_open = function(tokens, idx) {
  return `<h${tokens[idx].tag.slice(1)} class="custom-heading">`;
};

Здесь tokens[idx].tag содержит тег заголовка (h1, h2 и т.д.). Переопределение позволяет добавлять CSS-классы или другие атрибуты к элементам HTML.

Парсинг в токены

Для более сложных сценариев Markdown можно разобрать на токены:

const tokens = md.parse("# Заголовок\nТекст абзаца", {});
tokens.forEach(token => {
  console.log(token.type, token.tag, token.content);
});

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

Безопасная обработка HTML

Если нужно предотвратить выполнение произвольного HTML в Markdown, можно использовать библиотеку sanitize-html или другой фильтр:

const sanitizeHtml = require('sanitize-html');

const unsafeMarkdown = `<script>alert('xss');</script> **текст**`;
const html = md.render(unsafeMarkdown);
const safeHtml = sanitizeHtml(html);
console.log(safeHtml);

Это гарантирует, что на странице не будет внедрённого JavaScript.

Пример комплексного использования

const md = new MarkdownIt({ html: true, linkify: true, typographer: true });
const markdownText = `
# Документ

Пример [ссылки](https://example.com) и автоматическая ссылка: https://example.com

\`\`\`javascript
console.log("Hello, Markdown-it!");
\`\`\`
`;

const html = md.render(markdownText);
console.log(html);

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

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

Оглавление