rehype-slug: генерация идентификаторов заголовков

rehype-slug — это плагин для экосистемы Rehype, предназначенный для автоматической генерации идентификаторов (id) для заголовков в HTML-документах. Он используется для облегчения навигации, создания якорных ссылок и интеграции с другими инструментами, например, для генерации таблицы содержания (TOC).

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

Для использования rehype-slug необходимо установить пакет через npm или yarn:

npm install rehype-slug

или

yarn add rehype-slug

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

import { unified } from 'unified';
import rehypeParse from 'rehype-parse';
import rehypeStringify from 'rehype-stringify';
import rehypeSlug from 'rehype-slug';

const processor = unified()
  .use(rehypeParse, { fragment: true })
  .use(rehypeSlug)
  .use(rehypeStringify);

const html = `<h1>Пример заголовка</h1>`;
processor.process(html).then(file => {
  console.log(String(file));
});

После обработки заголовок <h1>Пример заголовка</h1> будет преобразован в <h1 id="primer-zagolovka">Пример заголовка</h1>.

Механизм генерации идентификаторов

rehype-slug преобразует текст заголовка в строку в стиле URL (slug), которая подходит для атрибута id. Процесс включает несколько шагов:

Нормализация текста: удаляются лишние пробелы и управляющие символы.
Транслитерация и приведение к нижнему регистру: кириллица и другие символы преобразуются в латиницу, все буквы становятся строчными.
Замена пробелов и специальных символов на дефисы: текст Заголовок 1! станет zagolovok-1.
Проверка уникальности: если идентификатор уже существует, добавляется числовой суффикс, например zagolovok-1-1.

Особенности работы с разными уровнями заголовков

rehype-slug обрабатывает все элементы заголовков HTML: <h1>–<h6>. При этом:

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

Интеграция с rehype-autolink-headings

Для удобного создания ссылок на заголовки часто используется связка rehype-slug + rehype-autolink-headings. Пример использования:

import rehypeAutolinkHeadings from 'rehype-autolink-headings';

const processor = unified()
  .use(rehypeParse, { fragment: true })
  .use(rehypeSlug)
  .use(rehypeAutolinkHeadings, {
    beh * avior: 'wrap'
  })
  .use(rehypeStringify);

const html = `<h2>Секция документа</h2>`;
processor.process(html).then(file => {
  console.log(String(file));
});

Результат:

<h2 id="sekciya-dokumenta">
  <a href="#sekciya-dokumenta">Секция документа</a>
</h2>

Атрибут id создаётся rehype-slug.
Плагин rehype-autolink-headings оборачивает заголовок в ссылку с соответствующим якорем.

Настройка slug-стиля

По умолчанию rehype-slug использует базовую транслитерацию и дефисы. Для проектов с особыми требованиями к формату идентификаторов можно использовать кастомные решения через промежуточные плагины или подключение rehype-slug вместе с unist-util-visit для ручной модификации id:

import { visit } from 'unist-util-visit';

function customSlug() {
  return (tree) => {
    visit(tree, 'element', (node) => {
      if (node.tagName && /^h[1-6]$/.test(node.tagName)) {
        const text = node.children
          .filter(c => c.type === 'text')
          .map(c => c.value)
          .join('-');
        node.properties.id = text.toLowerCase().replace(/\s+/g, '_');
      }
    });
  };
}

В этом примере пробелы заменяются на подчеркивания, что создаёт уникальный стиль идентификаторов, отличающийся от дефисного.