Оглавление Markdown в PDF: структура для удобной печати

Оглавление — это не элемент оформления. В документе длиннее нескольких страниц оно определяет, найдет ли читатель нужный раздел сразу или будет листать весь PDF вручную.

md2pdf умеет генерировать оглавление для одиночного документа и собирать сводное содержание для книги из нескольких глав. В этом руководстве объясняется, как работают обе функции, как выстроить заголовки и когда оглавление лучше отключить.

Для базовой конвертации см. Как преобразовать README с GitHub в PDF. Для сборки книг см. Создание книги из нескольких Markdown-файлов.

Чем на самом деле является оглавление

В режиме одного документа оглавление представляет собой блок HTML-навигации перед текстом Markdown. Оно выводит заголовки со ссылками на соответствующие разделы, которые работают в браузере и остаются кликабельными в PDF при поддержке драйвером печати.

Это не боковая панель закладок PDF-ридера. Закладки формируются на уровне движка печати и поддерживаются не всеми системами.

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

Как md2pdf строит оглавление

Оглавление формируется по четким правилам на основе разобранного Markdown:

• В документе должно быть не менее трех заголовков.
• Учитываются уровни от H1 до H4.
• Идентификаторы заголовков очищаются от дубликатов для уникальности ссылок.
• Переключатель на панели управляет одновременно предпросмотром и печатью.

# Project handbook

## Installation

### Requirements

## Configuration

### Environment variables

## Troubleshooting

Пример типичной структуры заголовков:

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

Пишите заголовки, понятные вне контекста

Заголовок решает две задачи: сообщает суть раздела и становится строкой в содержании. Слишком общие формулировки запутывают читателя.

Vague:  ## Overview
Useful: ## Configure GitHub access
Vague:  ## Errors
Useful: ## Recover from a failed export

Используйте конкретные формулировки:

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

Начинайте основные разделы с H2

Заголовок документа должен быть единственным H1, а основные разделы должны начинаться с H2:

1. Четкий верхний уровень. H1 обозначает весь документ.
2. Естественная вложенность. H3 и H4 становятся логичными подразделами.
3. Предсказуемые шрифты. Печатная страница выглядит целостно, а не как склейка разрозненных заметок.

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

Дубликаты, приложения и длинные документы

Хотя система технически разводит одинаковые заголовки суффиксами, в оглавлении они будут выглядеть одинаково. Уточняйте названия в исходном тексте.

Если документ огромен и содержит десятки H4, оглавление может занять несколько страниц. В таком случае детализируйте текст в абзацах, а в оглавлении оставьте H2 и H3.

Приложениям давайте полные имена, например ## Приложение А: Лимиты экспорта.

Когда оглавление стоит отключить

Оглавление незаменимо в руководствах, спецификациях и регламентах. В коротких заметках на 1–2 страницы его лучше отключить, чтобы не загромождать лист.

Проверьте оглавление в готовом PDF

Откройте сохраненный файл PDF и убедитесь, что ссылки ведут в нужные места, а верстка не ломается. Рекомендации по оформлению кода см. в статье Блоки кода Markdown в PDF.