Оглавление документа
Структура документа описывается в файле toc.yaml. На основе этого файла генерируется оглавление и происходит сборка документа.
Важно
Файлы, которые не указаны в toc.yaml, не обрабатываются при сборке.
Структура
Стандартная структура файла toc.yaml имеет вид:
title: Имя документа
href: index.yaml
items:
- name: Имя раздела
href: path/to/file.md
- name: Имя группы разделов
items:
- name: Имя раздела
href: path/to/file.md
- name: Имя раздела
href: path/to/file.md
- name: Имя раздела
href: path/to/file.md
В корне:
title— название документа. Отображается в оглавлении над списком всех разделов. Можно скрыть его отображение с помощью настройки interface: toc-header в файле .yfm.href— относительный путь до файла.items— пункты оглавления.
Каждый пункт оглавления содержит поля:
name— имя раздела или группы разделов.href— относительный путь до файла.items— список вложенных пунктов.
Для упрощения работы с большими оглавлениями и переиспользования блоков поддержана вставка оглавлений.
Условия видимости разделов
Отдельные разделы можно включать или не включать в документ в зависимости от значений переменных. Для описания условий видимости используется параметр when.
Доступные операторы сравнения: ==, !=, <, >, <=, >=.
- name: Раздел с условным вхождением
href: path/to/conditional/file.md
when: version == 12
Подстановки и условные операторы
Название документа поддерживает подстановки и условные операторы.
title: "{{ title }}"
Важно
Если значение начинается с подстановки, всегда заключайте его в кавычки. Без них значение обрабатывается как JSON, встроенный в YAML, что может привести к ошибкам сборки, например TypeError: str.replace is not a function.
Настройка раскрытия разделов
По умолчанию все разделы оглавления свернуты. Чтобы важные разделы и страницы в оглавлении всегда были на виду, можно использовать параметр expanded:
title: Yandex Cloud Marketplace
items:
- name: Начало работы
href: index.md
- name: Основы
expanded: true
items:
- name: Создание виртуальной машины
href: create.md
- name: Первичная настройка программного обеспечения
href: setup.md
- name: Работа с виртуальной машиной
href: operate.md
- name: Справочник API
href: guide.md
Важно
Использовать expanded можно только для разделов первого уровня, указание expanded в разделах ниже игнорируется.
Labeled-разделы в навигации
Специальные заголовки, которые визуально группируют отдельные пункты в оглавлении.
В файле toc.yaml у соответствующего пункта меню укажите атрибут labeled: true:
title: Имя документа
href: index.yaml
items:
- name: Имя раздела
labeled: true
href: path/to/file.md
- name: Имя группы разделов
labeled: true
items:
- name: Имя раздела
href: path/to/file.md
- name: Имя раздела
href: path/to/file.md
- name: Имя раздела
labeled: true
href: path/to/file.md
Скрытые разделы
Чтобы раздел был доступен только по прямой ссылке и не попал в оглавление, укажите параметр hidden.
- title: Секретный документ
href: secret.md
hidden: true
Для полного исключения скрытых разделов из сборки используйте ключ сборки --remove-hidden-toc-items=true.