Идентификаторы заголовков

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

Базовый синтаксис

Добавление идентификатора заголовка

Идентификатор заголовка использует синтаксис с фигурными скобками и размещается после текста заголовка:

## Мой заголовок {#custom-id}

Результат рендеринга:

HTML-вывод добавит этот пользовательский идентификатор к элементу заголовка:

<h2 id="custom-id">Мой заголовок</h2>

Идентификаторы заголовков разных уровней

Каждый уровень заголовка может иметь пользовательский идентификатор:

# Заголовок первого уровня {#first-level}

## Заголовок второго уровня {#second-level}

### Заголовок третьего уровня {#third-level}

#### Заголовок четвертого уровня {#fourth-level}

Области применения

Создание якорных ссылок

С пользовательскими идентификаторами вы можете создавать ссылки на конкретные части документа:

[Перейти к моему заголовку](#custom-id)

...другой контент...

## Мой заголовок {#custom-id}

Результат рендеринга:

При клике ссылка переведет вас непосредственно к заголовку с custom-id.

Внешние ссылки на определенные части документа

Пользовательские идентификаторы также упрощают ссылки на конкретные разделы из внешних документов:

[Ссылка на определенную главу другого документа](other-doc.html#specific-section)

Совместный доступ к определенным разделам через URL

Заголовки с идентификаторами можно делиться с другими через URL, указывающий на конкретную главу:

https://www.markdownlang.com/documentation.html#installation-guide

Расширенное использование

Идентификаторы для заголовков с несколькими словами

Когда заголовок содержит несколько слов, идентификатор обычно использует дефисы:

## Руководство по установке и настройке {#installation-and-configuration}

Генерация оглавления и идентификаторы заголовков

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

## Руководство по началу работы {#getting-started}

Даже если позже заголовок будет изменен на "Как начать", ссылка останется действительной, так как идентификатор остается неизменным.

Интернационализация и не-английские символы

Пользовательские идентификаторы особенно полезны для заголовков на не-английских языках, так как они предоставляют стабильный английский идентификатор:

## Инструкции по установке {#installation}

## Способы использования {#usage}

## Часто задаваемые вопросы {#faq}

Совместимость и различия в реализации

Поддержка различными платформами

Платформа/Инструмент	Поддержка идентификаторов заголовков	Синтаксис
GitHub Markdown	✅	{#id}
GitLab Markdown	✅	{#id}
Jekyll (kramdown)	✅	{:#id} или {#id}
Hugo	✅	{#id}
CommonMark	❌	Не поддерживается
VitePress	✅	{#id}
Pandoc	✅	{#id}

Правила автоматической генерации идентификаторов

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

1. Преобразование в нижний регистр
2. Удаление или замена специальных символов
3. Замена пробелов дефисами
4. Удаление повторяющихся дефисов
5. Обеспечение уникальности идентификатора (обычно добавлением числового суффикса)

Примеры:

Заголовок	Автоматически сгенерированный идентификатор
## Начало работы	#начало-работы
## Часто задаваемые вопросы и помощь	#часто-задаваемые-вопросы-и-помощь
## Быстрый старт	#быстрый-старт или #section-1 (в зависимости от платформы)

Лучшие практики

Соглашения по именованию идентификаторов заголовков

✅ Рекомендуемые подходы:

1. **Используйте краткие описательные идентификаторы**:
   - `{#installation}`
   - `{#api-reference}`
   - `{#troubleshooting}`

2. **Поддерживайте согласованный стиль именования**:
   - Все в нижнем регистре
   - Используйте дефисы для разделения слов
   - Избегайте подчеркиваний или верблюжьего регистра

3. **Обеспечьте стабильность идентификаторов**:
   - Избегайте частых изменений идентификаторов
   - Сохраняйте исходный идентификатор при изменении текста заголовка

❌ Что следует избегать:

1. Использование специальных символов (таких как `!@#$%^&*()`)
2. Использование неописательных идентификаторов (например, `{#section1}`)
3. Создание слишком длинных идентификаторов
4. Использование пробелов или знаков препинания

Структура документа и идентификаторы заголовков

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

# Документация продукта {#product-docs}

## Введение {#introduction}

## Установка {#installation}

### Установка на Windows {#installation-windows}

### Установка на macOS {#installation-macos}

### Установка на Linux {#installation-linux}

## Конфигурация {#configuration}

## Справочник по API {#api-reference}

## Часто задаваемые вопросы {#faq}

Практические примеры

Идентификаторы заголовков в технической документации

Идентификаторы заголовков в технической документации помогают пользователям напрямую ссылаться на конкретные главы:

# Документация по API {#api-documentation}