Копирование кода

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

npm install marked

После установки подключение в проекте выглядит так:

import { marked } from 'marked';

или в CommonJS:

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

Marked — это мощная библиотека для преобразования Markdown в HTML. Она предоставляет гибкие возможности как для простого рендеринга, так и для расширенной кастомизации.

Простейшее преобразование Markdown в HTML

Базовый синтаксис использования сводится к вызову функции marked() с текстом Markdown:

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

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

const html = marked(markdownText);
console.log(html);

Результатом будет HTML-структура:

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

Особенности:

  • Поддержка всех стандартных элементов Markdown: заголовки, списки, ссылки, изображения, цитаты.
  • Автоматическое экранирование HTML для предотвращения XSS уязвимостей (при включении соответствующей опции).

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

Marked позволяет изменять поведение парсера через объект options. Основные параметры:

marked.setOptions({
  renderer: new marked.Renderer(), // кастомный рендерер
  gfm: true,                       // поддержка GitHub Flavored Markdown
  breaks: false,                   // перенос строк как в HTML
  sanitize: false,                 // устаревший, использовать `DOMPurify` для безопасности
  smartLists: true,                // умные списки
  smartypants: true                // преобразование кавычек и тире
});

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

const renderer = new marked.Renderer();

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

const markdown = '# Тестовый заголовок';
const html = marked(markdown, { renderer });
console.log(html);

Результат:

<h1 class="custom-heading">Тестовый заголовок</h1>

Безопасное использование HTML

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

import DOMPurify from 'dompurify';

const unsafeMarkdown = `
<script>alert('XSS');</script>
**Жирный текст**
`;

const safeHTML = DOMPurify.sanitize(marked(unsafeMarkdown));
console.log(safeHTML);

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

Асинхронный парсинг

Marked поддерживает асинхронное преобразование, что особенно полезно при использовании расширений, подгружающих данные или обрабатывающих файлы на лету.

const asyncMarkdown = `
# Заголовок
[Ссылка](https://example.com)
`;

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

Расширения и плагины

Marked можно расширять через токены и лексеры:

  • Лексер (marked.Lexer) преобразует Markdown в токены.
  • Парсер (marked.Parser) превращает токены в HTML.
  • Кастомные токены позволяют создавать нестандартные блоки, например специальные уведомления или блоки кода с подсветкой.

Пример создания токена для блоков предупреждений:

const lexer = new marked.Lexer();

lexer.rules.block.warning = /^!!!\s+(.*)$/m;

const tokens = lexer.lex('!!! Внимание, это предупреждение!');
console.log(tokens);

Подсветка синтаксиса кода

Для кода в Markdown (```javascript ... ```) можно подключать подсветку синтаксиса через внешние библиотеки, например highlight.js:

import hljs from 'highlight.js';

marked.setOptions({
  highlight: function(code, lang) {
    return hljs.highlightAuto(code, [lang]).value;
  }
});

const markdownCode = `
\`\`\`javascript
console.log('Hello World');
\`\`\`
`;

const htmlCode = marked(markdownCode);
console.log(htmlCode);

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

Работа с отдельными блоками

Можно обрабатывать отдельные блоки Markdown без конвертации всего текста:

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

tokens.forEach(token => {
  if (token.type === 'heading') {
    console.log('Найден заголовок:', token.text, 'уровень:', token.depth);
  }
});

Такой подход удобен для генерации оглавлений или анализа документа.

Поддержка GitHub Flavored Markdown (GFM)

Опция gfm включает расширенный синтаксис:

  • таблицы
  • задачи (- [ ] и - [x])
  • автоссылки
  • зачёркнутый текст

Пример таблицы:

| Имя  | Возраст |
|------|---------|
| Иван | 25      |
| Анна | 30      |
marked.setOptions({ gfm: true });
const htmlTable = marked(markdownTable);
console.log(htmlTable);

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

  • Преобразование Markdown в HTML через marked().
  • Кастомизация рендеринга через Renderer.
  • Поддержка безопасного HTML через фильтрацию (DOMPurify).
  • Асинхронный парсинг и расширения через токены и лексеры.
  • Подсветка кода через внешние библиотеки.
  • Полная поддержка GitHub Flavored Markdown.

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

Оглавление