Популярные плагины

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

1. markdown-it-anchor

Назначение: Автоматическая генерация якорей для заголовков.

  • Позволяет создавать уникальные идентификаторы для <h1>–<h6> элементов.
  • Поддерживает пользовательские правила формирования slug.
  • Часто используется вместе с генерацией оглавления.

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

const MarkdownIt = require('markdown-it');
const markdownItAnchor = require('markdown-it-anchor');

const md = new MarkdownIt();
md.use(markdownItAnchor, {
  level: [1, 2, 3], // заголовки, для которых генерируются якоря
  slugify: s => s.trim().toLowerCase().replace(/\s+/g, '-') // кастомная функция для slug
});

const result = md.render('# Пример заголовка');
console.log(result);

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

  • Поддержка нескольких языков через кастомную функцию slugify.
  • Возможность добавлять символы ссылки рядом с заголовком.
  • Полезен для сайтов с динамическим оглавлением.

2. markdown-it-footnote

Назначение: Добавление поддержки сносок, как в LaTeX или Википедии.

  • Позволяет вставлять сноски через синтаксис [^1] и определять их в конце документа.
  • Генерирует ссылки на сноску и обратные ссылки на текст.

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

const MarkdownIt = require('markdown-it');
const markdownItFootnote = require('markdown-it-footnote');

const md = new MarkdownIt();
md.use(markdownItFootnote);

const result = md.render(`
Текст с сноской[^1].

[^1]: Текст сноски.
`);
console.log(result);

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

  • Автоматическая нумерация сносок.
  • Совместимость с HTML и другими плагинами.
  • Возможность кастомизации шаблона сноски через рендер-функции.

3. markdown-it-table-of-contents (markdown-it-toc-done-right)

Назначение: Генерация оглавления на основе заголовков Markdown-документа.

  • Создает структурированное оглавление с вложенными уровнями.
  • Поддерживает динамическое обновление при изменении заголовков.
  • Часто применяется вместе с markdown-it-anchor.

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

const MarkdownIt = require('markdown-it');
const markdownItAnchor = require('markdown-it-anchor');
const tocDoneRight = require('markdown-it-toc-done-right');

const md = new MarkdownIt();
md.use(markdownItAnchor);
md.use(tocDoneRight);

const result = md.render(`
[[toc]]

# Глава 1
## Подглава 1.1
# Глава 2
`);
console.log(result);

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

  • Позволяет указывать уровни заголовков для включения в оглавление.
  • Поддержка кастомного HTML и CSS для оформления TOC.
  • Удобно комбинировать с другими плагинами для расширенной навигации по документации.

4. markdown-it-katex

Назначение: Рендеринг математических формул с использованием синтаксиса LaTeX.

  • Поддерживает как инлайн, так и блочные формулы.
  • Генерирует HTML с использованием KaTeX для быстрой и точной визуализации формул.

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

const MarkdownIt = require('markdown-it');
const markdownItKatex = require('markdown-it-katex');

const md = new MarkdownIt();
md.use(markdownItKatex);

const result = md.render('Инлайн формула $E=mc^2$ и блочная формула: $$\\int_0^1 x^2 dx$$');
console.log(result);

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

  • Поддержка всех стандартных команд LaTeX.
  • Включение KaTeX CSS для корректного отображения.
  • Отлично подходит для учебников, документации по математике и физике.

5. markdown-it-emoji

Назначение: Преобразование текстовых смайликов в графические эмодзи.

  • Поддерживает стандартные коды :smile:, :heart: и другие.
  • Можно использовать кастомные замены.

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

const MarkdownIt = require('markdown-it');
const markdownItEmoji = require('markdown-it-emoji');

const md = new MarkdownIt();
md.use(markdownItEmoji);

const result = md.render('Привет :smile:');
console.log(result);

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

  • Полный набор Unicode-эмодзи.
  • Настраиваемый рендер через функцию md.renderer.rules.emoji.
  • Может работать в комбинации с HTML и другими плагинами Markdown-it.

6. markdown-it-container

Назначение: Создание пользовательских контейнеров для блоков контента.

  • Позволяет создавать “alert”, “note”, “tip” блоки с кастомным HTML.
  • Поддержка вложенных элементов и многострочных блоков.

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

const MarkdownIt = require('markdown-it');
const markdownItContainer = require('markdown-it-container');

const md = new MarkdownIt();
md.use(markdownItContainer, 'note', {
  render(tokens, idx) {
    if (tokens[idx].nesting === 1) {
      return '<div class="note">';
    } else {
      return '</div>';
    }
  }
});

const result = md.render(`
:::note
Это блок заметки.
:::
`);
console.log(result);

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

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

7. markdown-it-abbr

Назначение: Поддержка сокращений и аббревиатур.

  • Позволяет создавать определения для сокращений через синтаксис *[HTML]: Hyper Text Markup Language.
  • Автоматическая расшифровка при первом упоминании.

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

const MarkdownIt = require('markdown-it');
const markdownItAbbr = require('markdown-it-abbr');

const md = new MarkdownIt();
md.use(markdownItAbbr);

const result = md.render(`
Это пример аббревиатуры HTML.

*[HTML]: Hyper Text Markup Language
`);
console.log(result);

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

  • Улучшает читаемость технических текстов.
  • Легко интегрируется с другими плагинами Markdown-it.
  • Поддерживает несколько аббревиатур в документе.

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

Оглавление