Снапшот-тестирование

Marked — это высокопроизводительная библиотека для парсинга Markdown в HTML на JavaScript. Она предоставляет гибкий API для обработки текста, включая возможность кастомизации рендеринга, работу с токенами и расширение функционала через плагины. Библиотека подходит как для клиентской, так и для серверной разработки (Node.js).

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

Для установки в проект через npm используется команда:

npm install marked

Подключение в Node.js:

const { marked } = require('marked');

В среде браузера можно использовать CDN:

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

Парсинг Markdown в HTML

Основная задача Marked — преобразование текста в формате Markdown в HTML. Простейший пример:

const markdown = "# Заголовок 1\n\nЭто пример текста.";
const html = marked(markdown);
console.log(html);

Результат:

<h1>Заголовок 1</h1>
<p>Это пример текста.</p>

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

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

Marked предоставляет объект options, с помощью которого можно настроить работу парсера:

marked.setOptions({
  renderer: new marked.Renderer(),
  gfm: true,              // поддержка GitHub Flavored Markdown
  breaks: true,           // перевод строк как <br>
  smartLists: true,       // умные списки
  smartypants: true       // типографские символы
});

Ключевые параметры:

  • renderer — объект для переопределения методов рендеринга.
  • gfm — включает расширенный синтаксис Markdown, как в GitHub.
  • breaks — автоматически преобразует переводы строк в <br>.
  • smartLists — корректно обрабатывает вложенные списки.
  • smartypants — заменяет кавычки и дефисы на типографские аналоги.

Кастомизация рендеринга

Объект Renderer позволяет изменять HTML, создаваемый для разных элементов Markdown:

const renderer = new marked.Renderer();

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

const html = marked("# Пример", { renderer });
console.log(html);

Каждый метод рендерера соответствует конкретному элементу Markdown: paragraph, list, listitem, link, image, code и т.д.

Использование токенов

Marked предоставляет возможность работы с токенами для детальной обработки Markdown. Метод lexer разбивает текст на массив токенов:

const tokens = marked.lexer("# Заголовок\n\nТекст параграфа");
console.log(tokens);

Пример токена заголовка:

{
  "type": "heading",
  "depth": 1,
  "text": "Заголовок"
}

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

Парсинг и рендеринг с безопасностью

Для предотвращения XSS-атак рекомендуется использовать параметр sanitize или внешние библиотеки вроде DOMPurify:

const dirtyHtml = marked("<script>alert('xss')</script>");
const cleanHtml = DOMPurify.sanitize(dirtyHtml);

Асинхронный рендеринг

Marked поддерживает асинхронную обработку через функцию marked.parse с колбэком или промисом:

const markdown = "Пример с асинхронной обработкой";

marked.parse(markdown, (err, html) => {
  if (err) throw err;
  console.log(html);
});

Это полезно при интеграции с внешними сервисами или при загрузке больших Markdown-файлов.

Интеграция с редакторами и тестирование

Marked активно используется для динамической генерации HTML в редакторах, просмотре документации и фронтенд-приложениях. В связке со Snapshots-тестами можно контролировать корректность преобразования Markdown:

import { marked } from 'marked';

test('Markdown рендерится корректно', () => {
  const markdown = "# Тестовый заголовок";
  const html = marked(markdown);
  expect(html).toMatchSnapshot();
});

Snapshot-тестирование позволяет фиксировать изменения в выводе HTML и отслеживать непреднамеренные изменения в рендеринге.

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

Marked поддерживает расширения через walkTokens и кастомные лексеры:

marked.use({
  walkTokens(token) {
    if (token.type === 'text') {
      token.text = token.text.replace(/важно/g, '<strong>важно</strong>');
    }
  }
});

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

Заключение ключевых возможностей

  • Высокая производительность и совместимость с Node.js и браузером.
  • Гибкая настройка рендерера и поддержка расширенного синтаксиса GFM.
  • Работа с токенами и асинхронное преобразование Markdown.
  • Возможность интеграции с системами тестирования через Snapshots.
  • Простое расширение функционала с помощью кастомных правил и плагинов.

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

Оглавление