Параметр headerIds

Параметр headerIds управляет генерацией уникальных идентификаторов (id) для заголовков при преобразовании Markdown в HTML. В HTML идентификаторы заголовков необходимы для создания якорных ссылок, организации навигации по документу и автоматической генерации оглавлений. В библиотеке Marked этот параметр предоставляет гибкий контроль над этой функциональностью.

Тип и значения

Параметр headerIds принимает булево значение:

  • true — для автоматической генерации id для всех заголовков (<h1>–<h6>), если они не имеют собственного id.
  • false — отключает генерацию id, заголовки будут рендериться без атрибута id.

По умолчанию headerIds установлен в true, что обеспечивает совместимость с большинством систем, требующих уникальные идентификаторы.

Механизм генерации

Когда headerIds включен, библиотека Marked генерирует id на основе текста заголовка:

  1. Пробелы заменяются на дефисы.
  2. Все символы приводятся к нижнему регистру.
  3. Специальные символы удаляются или заменяются безопасными эквивалентами.
  4. Если в документе встречается одинаковый текст заголовка несколько раз, Marked добавляет числовой суффикс для обеспечения уникальности (например, #section, #section-1, #section-2).

Пример:

import { marked } from 'marked';

const markdown = `
# Введение
## Основы
# Введение
`;

const html = marked(markdown, { headerIds: true });
console.log(html);

Результат будет следующим:

<h1 id="vvedenie">Введение</h1>
<h2 id="osnovy">Основы</h2>
<h1 id="vvedenie-1">Введение</h1>

Настройка префикса для идентификаторов

Для большей гибкости Marked позволяет использовать параметр headerPrefix вместе с headerIds. Этот параметр добавляет префикс ко всем автоматически генерируемым идентификаторам заголовков:

const html = marked(markdown, { headerIds: true, headerPrefix: 'sec-' });

Результат:

<h1 id="sec-vvedenie">Введение</h1>
<h2 id="sec-osnovy">Основы</h2>
<h1 id="sec-vvedenie-1">Введение</h1>

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

Взаимодействие с пользовательскими рендерерами

Marked предоставляет возможность определять собственный рендерер через класс Renderer. При этом поведение headerIds можно полностью кастомизировать. Метод heading рендерера получает параметры: текст заголовка, уровень заголовка и сгенерированный id. Это позволяет создавать более сложные правила генерации, например:

import { marked } from 'marked';

const renderer = {
  heading(text, level, rawId) {
    const customId = 'custom-' + rawId;
    return `<h${level} id="${customId}">${text}</h${level}>`;
  }
};

const html = marked('# Пример заголовка', { renderer, headerIds: true });
console.log(html);

Вывод:

<h1 id="custom-primer-zagolovka">Пример заголовка</h1>

Ограничения и особенности

  • Если заголовок уже содержит атрибут id, автоматическая генерация игнорируется.
  • headerIds не влияет на вложенные HTML-теги внутри заголовков — они обрабатываются как часть текста.
  • При отключении headerIds (headerIds: false) необходимо самостоятельно обеспечивать уникальные идентификаторы, если они нужны для навигации или оглавлений.

Практические рекомендации

  • Использовать headerIds: true для документов с динамически генерируемой навигацией.
  • Добавлять headerPrefix, если на странице будут объединены несколько Markdown-файлов.
  • При сложной логике формирования id подключать кастомный рендерер через метод heading.
  • Проверять уникальность заголовков при автоматической генерации, особенно в больших документах.

Использование параметра headerIds является ключевым для поддержки структурированного и навигационного HTML при работе с Marked. Правильная настройка этого параметра позволяет создавать читабельные, удобные для ссылок и SEO-дружественные документы.

Оглавление