Первый пример использования

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

npm install markdown-it

После установки библиотеку можно подключить в проекте:

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

Инициализация Markdown-it происходит через создание нового экземпляра класса:

const md = new MarkdownIt();

Этот объект предоставляет методы для парсинга Markdown в HTML.

Простейший пример конвертации Markdown в HTML

После инициализации можно сразу конвертировать текст в HTML с помощью метода render:

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

Это **жирный** текст, а это *курсив*.
`;

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

Метод render принимает строку с Markdown и возвращает строку с HTML. Результат будет выглядеть следующим образом:

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

Настройка Markdown-it через опции

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

const md = new MarkdownIt({
  html: true,        // разрешить HTML в тексте
  linkify: true,     // автоматически преобразовывать ссылки в теги <a>
  typographer: true  // включить улучшенные типографские замены
});
  • html: если установлено в true, любые HTML-теги в исходном тексте не будут экранироваться.
  • linkify: автоматически преобразует текстовые ссылки (http://example.com) в кликабельные теги <a>.
  • typographer: включает умные кавычки, тире и другие типографские улучшения.

Добавление плагинов

Markdown-it построен на системе плагинов. Это позволяет расширять функциональность без модификации ядра. Пример подключения плагина markdown-it-emoji:

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

md.use(emoji);

const result = md.render('Hello :smile:');
console.log(result);

Вывод будет:

<p>Hello ?</p>

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

Работа с inline и block токенами

Markdown-it разбивает текст на токены двух типов: block (блочные элементы) и inline (встроенные элементы). Можно получить список токенов для анализа:

const tokens = md.parse(markdownText, {});
console.log(tokens);

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

Прямое рендеринг отдельных токенов

Иногда требуется конвертировать только часть текста. Для этого можно использовать метод renderInline:

const inlineResult = md.renderInline('**Жирный текст** и *курсив*');
console.log(inlineResult);

Результат:

<strong>Жирный текст</strong> и <em>курсив</em>

Метод renderInline пропускает создание блочных элементов, таких как <p> или <h1>.

Пример интеграции с веб-приложением

Markdown-it можно использовать для динамического рендеринга Markdown в браузере. Пример с Node.js и Express:

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

const app = express();
const md = new MarkdownIt();

app.use(express.urlencoded({ extended: true }));

app.post('/render', (req, res) => {
  const markdownText = req.body.text || '';
  const html = md.render(markdownText);
  res.send(html);
});

app.listen(3000, () => console.log('Server running on port 3000'));

В этом примере сервер принимает Markdown через POST-запрос и возвращает HTML.

Особенности работы с безопасностью

При включении опции html: true необходимо учитывать потенциальные XSS-уязвимости, если пользовательский ввод напрямую преобразуется в HTML. Для защиты можно использовать библиотеки вроде DOMPurify или экранировать нежелательные теги вручную.

Выводы по первому примеру

Markdown-it предоставляет лёгкий и гибкий механизм для работы с Markdown:

  • Поддерживает базовую конвертацию Markdown → HTML.
  • Настраивается через опции.
  • Расширяется с помощью плагинов.
  • Позволяет работать с токенами для продвинутого анализа.
  • Может интегрироваться с веб-приложениями.

Благодаря этим особенностям библиотека подходит как для простых, так и для сложных задач по обработке Markdown.

Оглавление