Якоря заголовков

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

Автоматическая генерация якорей

По умолчанию Markdown не добавляет идентификаторы к заголовкам. В Markdown-it идентификаторы можно создавать с помощью плагина markdown-it-anchor.

Установка плагина:

npm install markdown-it markdown-it-anchor

Подключение и базовое использование:

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

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

const result = md.render('# Заголовок 1');
console.log(result);

Результат:

<h1 id="заголовок-1">Заголовок 1</h1>

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

Настройка формата якорей

Плагин markdown-it-anchor поддерживает кастомные функции для генерации ID. Это позволяет управлять форматом якорей, избегать дублирования и использовать собственные правила трансформации текста.

Пример с кастомной функцией:

md.use(markdownItAnchor, {
  slugify: s => s.trim().toLowerCase().replace(/\s+/g, '_')
});

const result = md.render('## Раздел Пример');
console.log(result);

Результат:

<h2 id="раздел_пример">Раздел Пример</h2>

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

  • slugify принимает строку заголовка.
  • Должна возвращать валидный HTML-идентификатор.
  • Можно использовать любые правила: замена пробелов, удаление спецсимволов, транслитерация.

Добавление ссылок на заголовки

Markdown-it позволяет создавать ссылки на заголовки для удобной навигации внутри страницы.

Пример:

const md = new MarkdownIt()
  .use(markdownItAnchor, {
    permalink: true,
    permalinkSymbol: '¶',
    permalinkBefore: true
  });

const result = md.render('### Подраздел');
console.log(result);

Результат:

<h3 id="подраздел">
  <a class="header-anchor" href="#подраздел">¶</a>
  Подраздел
</h3>

Разбор параметров:

  • permalink: true — включение автоматической вставки ссылок.
  • permalinkSymbol: '¶' — символ ссылки на заголовок.
  • permalinkBefore: true — вставка символа перед текстом заголовка.

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

Обработка дублей идентификаторов

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

md.use(markdownItAnchor, { uniqueSlugStartIndex: 1 });

Пример:

## Раздел
## Раздел

Рендеринг:

<h2 id="раздел">Раздел</h2>
<h2 id="раздел-1">Раздел</h2>

Ключевые моменты:

  • uniqueSlugStartIndex задаёт начальное число для суффикса.
  • Можно полностью управлять логикой уникальности через кастомную функцию uniqueSlugCallback.

Интеграция с другими плагинами

Markdown-it и markdown-it-anchor легко комбинируются с плагинами для оглавления, подсветки кода и кастомных стилей:

  • markdown-it-table-of-contents — автоматическое создание оглавления.
  • markdown-it-highlightjs — подсветка синтаксиса кода.
  • Можно передавать уже сгенерированные ID для создания навигации на фронтенде.

Пример интеграции с оглавлением:

const markdownItTOC = require('markdown-it-table-of-contents');

md.use(markdownItAnchor)
  .use(markdownItTOC, { includeLevel: [1, 2, 3] });

const result = md.render('[toc]\n\n# Введение\n## Раздел 1\n### Подраздел A');

Результат: [toc] заменяется на HTML-структуру с ссылками на якоря заголовков.

Продвинутая настройка якорей

Для крупных проектов часто требуется:

  1. Игнорировать определённые заголовки.
  2. Добавлять классы CSS к ссылкам.
  3. Использовать разные стили для разных уровней заголовков.

Пример:

md.use(markdownItAnchor, {
  level: [1,2,3],
  permalink: true,
  permalinkClass: 'custom-anchor',
  permalinkSymbol: '?',
  slugify: s => s.toLowerCase().replace(/[^\w]+/g, '-')
});
  • level — массив уровней заголовков, для которых создаются якоря.
  • permalinkClass — CSS-класс для ссылки на заголовок.
  • slugify — универсальная функция для генерации безопасных ID.

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

Оглавление