Плагин для якорей

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

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

Для работы с плагином якорей обычно используют пакет markdown-it-anchor. Установка выполняется через npm:

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, {
  level: [1, 2, 3],
  permalink: true,
  permalinkSymbol: '¶',
  permalinkBefore: true,
  slugify: s => encodeURIComponent(String(s).trim().toLowerCase().replace(/\s+/g, '-'))
});

Разбор параметров конфигурации:

  • level — массив уровней заголовков, для которых будут генерироваться якоря. Например, [1, 2, 3] означает <h1>, <h2> и <h3>.
  • permalink — логическое значение, включающее или отключающее отображение символа ссылки на заголовок.
  • permalinkSymbol — символ, который будет отображаться рядом с заголовком для создания ссылки на якорь.
  • permalinkBefore — определяет, будет ли символ ссылки отображаться перед текстом заголовка (true) или после (false).
  • slugify — функция, преобразующая текст заголовка в идентификатор (якорь). В примере используется простое преобразование в нижний регистр и замена пробелов на дефисы.

Принцип работы плагина

Плагин анализирует AST (Abstract Syntax Tree), создаваемый Markdown-it при парсинге Markdown. Для каждого заголовка выбранного уровня создаётся уникальный id, который затем используется для ссылки. Если включён permalink, плагин вставляет HTML-элемент с ссылкой на этот id. В результате заголовок становится кликабельным и его можно использовать для внутренней навигации.

Пример Markdown:

# Основы JavaScript
## Переменные
### Типы данных

Рендер с включённым плагином создаст HTML:

<h1 id="osnovy-javascript">
  <a class="header-anchor" href="#osnovy-javascript">¶</a>
  Основы JavaScript
</h1>
<h2 id="peremennye">
  <a class="header-anchor" href="#peremennye">¶</a>
  Переменные
</h2>
<h3 id="tipy-dannyh">
  <a class="header-anchor" href="#tipy-dannyh">¶</a>
  Типы данных
</h3>

Настройка генерации уникальных идентификаторов

В больших документах важно избегать дублирующихся id. Плагин автоматически добавляет числовой суффикс при повторении идентификатора. Можно изменить этот механизм через кастомную функцию slugify:

const usedIds = new Set();

md.use(markdownItAnchor, {
  slugify: s => {
    let slug = encodeURIComponent(s.trim().toLowerCase().replace(/\s+/g, '-'));
    let originalSlug = slug;
    let i = 1;
    while (usedIds.has(slug)) {
      slug = `${originalSlug}-${i++}`;
    }
    usedIds.add(slug);
    return slug;
  }
});

Пермалинк с кастомным HTML

Иногда требуется не просто символ, а полноценная иконка или кнопка. Плагин поддерживает параметр permalinkClass и permalinkHref, а также возможность использовать функцию renderPermalink для полной кастомизации:

md.use(markdownItAnchor, {
  renderPermalink: (slug, opts, state, idx) => {
    const link = `<a class="custom-anchor" href="#${slug}" title="Ссылка на заголовок">${opts.permalinkSymbol}</a>`;
    state.tokens[idx + 1].children.unshift({
      type: 'html_inline',
      content: link
    });
  },
  permalinkSymbol: '?'
});

Использование с другими плагинами

Markdown-it поддерживает цепочку плагинов. Плагин якорей можно использовать совместно с markdown-it-toc-done-right для генерации оглавления:

const markdownItToc = require('markdown-it-toc-done-right');

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

В этом случае оглавление автоматически ссылается на заголовки с якорями.

Советы по интеграции

  • Всегда задавать уникальные функции slugify в больших документах.
  • При создании статических сайтов удобно включать permalinkBefore: true для удобного копирования ссылки.
  • Использовать кастомный renderPermalink, если требуется интеграция с CSS-иконками или кнопками навигации.
  • Проверять совместимость с другими плагинами, чтобы не нарушать последовательность рендеринга AST.

Плагин для якорей — ключевой инструмент для структурированных документов на Markdown, обеспечивающий удобство навигации и совместимость с автоматической генерацией оглавления.

Оглавление