Webpack и сборщики

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

Установка и интеграция

Для работы с Markdown-it в проекте на Node.js используется npm или yarn:

npm install markdown-it

Или

yarn add markdown-it

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

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

Для использования в браузере доступна версия через CDN:

<script src="https://cdn.jsdelivr.net/npm/markdown-it/dist/markdown-it.min.js"></script>
<script>
  const md = window.markdownit();
</script>

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

Создание HTML из Markdown выполняется через метод render:

const markdown = '# Заголовок\n\nТекст с **жирным** выделением.';
const html = md.render(markdown);
console.log(html);

Результат:

<h1>Заголовок</h1>
<p>Текст с <strong>жирным</strong> выделением.</p>

Для однострочного Markdown используется renderInline, которая не добавляет обёртку <p>:

const inlineHtml = md.renderInline('Текст с *курсивом*');
console.log(inlineHtml);

Настройка Markdown-it

Конструктор MarkdownIt принимает объект конфигурации:

const md = new MarkdownIt({
  html: true,        // Разрешает HTML-теги в тексте
  xhtmlOut: false,   // Генерирует XHTML вместо HTML
  breaks: true,      // Переносы строк как <br>
  linkify: true,     // Автоматическая конвертация ссылок
  typographer: true  // Замена стандартных символов на типографские
});

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

  • html — управление безопасностью и вставкой HTML.
  • breaks — полезно для блогов и комментариев, где важны переносы.
  • linkify — автоматически превращает URL в ссылки <a>.
  • typographer — преобразует кавычки, тире, многоточия в красивые HTML-сущности.

Плагины и расширения

Markdown-it имеет богатый экосистемный слой плагинов. Примеры:

const markdownItAnchor = require('markdown-it-anchor');
md.use(markdownItAnchor, { permalink: true, level: [1,2,3] });
  • markdown-it-anchor — добавляет якоря к заголовкам.
  • markdown-it-footnote — поддержка сносок.
  • markdown-it-table-of-contents — автогенерация оглавления.
  • markdown-it-emoji — преобразует :smile: в символы Unicode.

Для подключения плагина используется метод use с опциями.

Создание пользовательских правил

Markdown-it позволяет переопределять существующие правила или добавлять новые через renderer и parser rules. Пример добавления кастомного синтаксиса:

md.inline.ruler.after('emphasis', 'highlight', function(state, silent) {
  const start = state.pos;
  if (state.src[start] !== '^') return false;
  
  let match = state.src.slice(start + 1).match(/([^^]+)\^/);
  if (!match) return false;

  if (!silent) {
    const token = state.push('highlight', 'mark', 0);
    token.content = match[1];
  }
  
  state.pos += match[0].length + 1;
  return true;
});

md.renderer.rules.highlight = function(tokens, idx) {
  return `<mark>${tokens[idx].content}</mark>`;
};

После этого запись ^выделение^ превращается в HTML <mark>выделение</mark>.

Оптимизация и интеграция с Webpack

При использовании Markdown-it в проектах с Webpack, часто применяют следующие подходы:

  1. Лоадер markdown:

    npm install raw-loader --save-dev

    В webpack.config.js:

    module.exports = {
  module: {
    rules: [
      {
        test: /\.md$/,
        use: 'raw-loader'
      }
    ]
  }
};

    После чего Markdown-файлы импортируются как строки:

    import readme from './README.md';
const html = md.render(readme);

  2. Плагины для преобразования при сборке — позволяют генерировать HTML-страницы прямо из Markdown на этапе сборки.

  3. Tree-shaking — подключение только необходимых функций Markdown-it снижает размер итогового бандла.

Безопасность и фильтрация

Markdown-it предоставляет базовые возможности обработки HTML, но при необходимости защиты от XSS рекомендуется использовать DOMPurify или sanitize-html:

const DOMPurify = require('dompurify')(window);
const cleanHtml = DOMPurify.sanitize(md.render(markdown));

Это позволяет безопасно отображать пользовательский Markdown без угроз безопасности.

Практические приёмы

  • Поддержка шаблонов: Markdown можно комбинировать с шаблонизаторами для генерации страниц.
  • Кеширование рендеринга: для больших текстов полезно сохранять HTML, чтобы не рендерить Markdown при каждом запросе.
  • Многоуровневые плагины: можно объединять плагины, например, якоря и оглавление, для создания интерактивной документации.

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

Оглавление