Генерация документации

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

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

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

npm install marked

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

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

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

<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
<script>
  const html = marked.parse('# Заголовок');
</script>

Парсинг Markdown

Базовая функция marked.parse() преобразует текст Markdown в HTML:

const markdownText = `
# Заголовок первого уровня
Текстовый абзац с **жирным выделением** и *курсивом*.
`;

const htmlContent = marked.parse(markdownText);
console.log(htmlContent);

Результат:

<h1>Заголовок первого уровня</h1>
<p>Текстовый абзац с <strong>жирным выделением</strong> и <em>курсивом</em>.</p>

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

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

const renderer = new marked.Renderer();

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

renderer.link = (href, title, text) => {
  return `<a href="${href}" title="${title || text}" target="_blank">${text}</a>`;
};

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

Опции конфигурации

Marked предоставляет широкий набор опций для управления парсингом Markdown:

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

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

const options = {
  gfm: true,
  breaks: true,
  smartLists: true,
  headerIds: true,
  mangle: false
};

const htmlWithOptions = marked.parse(markdownText, options);

Поддержка токенов и лексический анализ

Marked выполняет предварительный разбор Markdown на токены с помощью функции marked.lexer():

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

Это позволяет анализировать структуру документа и программно обрабатывать элементы перед генерацией HTML. Каждому элементу присваивается тип: heading, paragraph, list, link, code и т.д.

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

Для работы с большими файлами документации или динамическими источниками Marked поддерживает асинхронную обработку:

const fs = require('fs').promises;

async function renderMarkdownFile(filePath) {
  const content = await fs.readFile(filePath, 'utf-8');
  const html = await marked.parse(content);
  return html;
}

renderMarkdownFile('./docs/example.md').then(console.log);

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

В генераторах документации Marked часто используют для:

  • Преобразования .md файлов в HTML-страницы.
  • Встраивания синтаксической подсветки с помощью Highlight.js.
  • Автоматической генерации оглавления по заголовкам документа.

Пример с подсветкой кода:

const hljs = require('highlight.js');

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

const codeMarkdown = '```javascript\nconsole.log("Hello World");\n```';
const htmlCode = marked.parse(codeMarkdown);

Расширяемость через плагины

Marked поддерживает расширяемость через хуки и кастомные обработчики токенов:

  • walkTokens(token) — функция для обхода всех токенов перед рендерингом.
  • tokenizer — позволяет создавать собственные правила для новых типов Markdown-синтаксиса.
  • renderer — полный контроль над генерацией HTML.

Пример использования walkTokens:

marked.use({
  walkTokens: token => {
    if (token.type === 'text') {
      token.text = token.text.replace(/TODO:/g, '<strong>TODO:</strong>');
    }
  }
});

const htmlTokens = marked.parse('TODO: реализовать функцию');

Оптимизация производительности

Marked ориентирован на скорость, но при генерации больших наборов документации полезно:

  • Использовать предварительный разбор через lexer() для анализа и фильтрации.
  • Кэшировать результат рендеринга отдельных разделов.
  • Включать только необходимые опции парсера.

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

  1. Генерация HTML-документов с кастомными стилями и подсветкой кода.
  2. Автоматическое создание оглавления и ссылок на заголовки.
  3. Преобразование Markdown-описаний API в веб-страницы документации.
  4. Обработка Markdown в реальном времени для редакторов и предпросмотра.

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

Оглавление