Что такое Marked

Marked — это библиотека на JavaScript для парсинга и рендеринга Markdown в HTML. Она обеспечивает высокую скорость работы, поддержку расширений и гибкую настройку. В основе работы лежит трансформация Markdown-разметки в HTML-код, что позволяет использовать её как на сервере, так и в браузере.

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

Для использования Marked в проекте на Node.js библиотеку устанавливают через npm:

npm install marked

В браузере подключение возможно через CDN:

<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>

После подключения объект marked становится доступен и предоставляет набор методов для работы с Markdown.

Простейшее использование

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

const marked = require('marked');

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

**Жирный текст** и *курсив*.
`;

const html = marked.parse(markdownString);
console.log(html);

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

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

Метод marked.parse() является основным способом получения HTML-кода из Markdown.

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

Marked предоставляет объект marked.Renderer, позволяющий переопределять стандартные элементы HTML. Например:

const renderer = new marked.Renderer();

renderer.heading = (text, level) => {
  return `<h${level} class="custom-heading">${text}</h${level}>`;
};

const html = marked.parse('# Заголовок', { renderer });
console.log(html);

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

Параметры конфигурации

Marked поддерживает множество настроек через объект конфигурации:

  • gfm (boolean) — включает поддержку GitHub Flavored Markdown (по умолчанию true).
  • breaks (boolean) — переводит одинарный перенос строки в <br>.
  • smartLists (boolean) — улучшенные списки.
  • smartypants (boolean) — замена обычных кавычек и тире на типографские символы.
  • headerIds (boolean) — автоматически генерировать ID для заголовков.
  • mangle (boolean) — предотвращение преобразования email-адресов в ссылки.

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

marked.setOptions({
  gfm: true,
  breaks: true,
  smartLists: true,
  smartypants: true
});

Лексический анализ и токены

Marked разбивает Markdown на токены с помощью встроенного лексера:

const tokens = marked.lexer(markdownString);
console.log(tokens);

Лексер возвращает массив объектов, где каждый объект представляет отдельный элемент Markdown, например заголовок, параграф, список и т.д. Это удобно для анализа документа и построения кастомного рендерера.

Асинхронная обработка

Для работы с большими объемами Markdown или при необходимости асинхронного рендеринга Marked предоставляет marked.parseAsync():

(async () => {
  const html = await marked.parseAsync(markdownString);
  console.log(html);
})();

Асинхронная версия поддерживает все опции и кастомные рендереры, что делает её удобной для работы в серверных приложениях с большим количеством данных.

Безопасность и XSS

По умолчанию Marked не фильтрует HTML внутри Markdown. Для предотвращения XSS-атак рекомендуется использовать дополнительную библиотеку, например DOMPurify:

const DOMPurify = require('dompurify');
const dirtyHtml = marked.parse(markdownString);
const cleanHtml = DOMPurify.sanitize(dirtyHtml);

Это особенно важно при работе с пользовательским вводом.

Расширение функциональности

Marked поддерживает расширения через кастомные токены и рендереры. Можно добавить поддержку новых синтаксисов, нестандартных блоков кода или интеграцию с другими библиотеками. Это делает Marked гибким инструментом для построения Markdown-редакторов и конвертеров.

Примеры интеграции

  • Редакторы Markdown: интеграция с textarea для моментального отображения HTML.
  • Статические генераторы сайтов: конвертация файлов .md в HTML-страницы.
  • Документация API: генерация документации из Markdown-файлов с поддержкой кастомных стилей и ссылок.

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

Оглавление