Параметр headerPrefix

Библиотека Marked в JavaScript является мощным инструментом для парсинга Markdown в HTML. Одним из полезных параметров конфигурации является headerPrefix, который позволяет управлять генерацией идентификаторов (ID) для заголовков. Этот параметр особенно важен при создании автоматической навигации, оглавлений или ссылок на секции документа.

Назначение headerPrefix

headerPrefix определяет префикс, который будет добавлен к атрибуту id каждого заголовка в HTML. Если заголовок преобразуется в HTML следующим образом:

## Основные функции

Без использования headerPrefix результат будет примерно таким:

<h2 id="основные-функции">Основные функции</h2>

Если задать headerPrefix: 'section-', ID заголовка изменится:

<h2 id="section-основные-функции">Основные функции</h2>

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

Типы значений

Параметр headerPrefix может принимать несколько видов значений:

  1. Строка Простое значение, добавляемое к каждому ID. Пример:

    marked.setOptions({
  headerPrefix: 'chapter-'
});

    Результат:

    <h3 id="chapter-примеры">Примеры</h3>

  2. Функция Позволяет динамически формировать префикс на основе содержимого заголовка и его уровня:

    marked.setOptions({
  headerPrefix: (header, level) => `lvl${level}-` + header.toLowerCase().replace(/\s+/g, '-')
});

    В этом случае заголовок:

    ### Настройка

    Превратится в:

    <h3 id="lvl3-настройка">Настройка</h3>

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

Влияние на навигацию

Добавление префикса к заголовкам напрямую влияет на работу якорных ссылок:

<a href="#section-основные-функции">Перейти к Основные функции</a>

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

Советы по использованию

  • Для проектов с множественными Markdown-документами использовать префиксы, включающие название документа, чтобы избежать дублирования ID:

    headerPrefix: 'doc1-'

  • Для динамически генерируемых страниц рекомендуется применять функцию, формирующую ID из заголовка, преобразованного к kebab-case, с добавлением уникального префикса.

  • Если необходимо полностью контролировать формат ID, можно комбинировать headerPrefix с пользовательской функцией slugger:

    const slugger = new marked.Slugger();
marked.setOptions({
  headerPrefix: header => `custom-${slugger.slug(header)}`
});

Совместимость с другими опциями Marked

headerPrefix работает в паре с другими опциями, влияющими на заголовки:

  • headerIds – включает или отключает генерацию ID для заголовков. Если headerIds отключен, headerPrefix не будет применяться.
  • mangle – изменяет содержимое заголовков для защиты от спама. Если используется вместе с headerPrefix, префикс добавляется перед изменённым ID.

Примеры практического использования

  1. Статический сайт с несколькими страницами
marked.setOptions({
  headerPrefix: 'page1-'
});

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

  1. Документация API
marked.setOptions({
  headerPrefix: (header, level) => `api-${level}-` + header.toLowerCase().replace(/\W+/g, '-')
});

Это обеспечивает уникальные и читаемые идентификаторы для всех заголовков API-документации.

  1. Интерактивные оглавления

Используя headerPrefix вместе с генерацией навигации через Jav * aScript:

document.querySelectorAll('h2, h3').forEach(h => {
  const link = document.createElement('a');
  link.href = '#' + h.id;
  link.textContent = h.textContent;
  toc.appendChild(link);
});

headerPrefix гарантирует, что ссылки в оглавлении не пересекутся с другими элементами страницы.

headerPrefix — простой, но крайне важный инструмент в Marked для создания уникальных, предсказуемых идентификаторов заголовков. Его правильное использование повышает надёжность навигации, упрощает интеграцию с таблицами содержания и предотвращает коллизии при работе с большими Markdown-документами.

Оглавление