Оглавление документа
Структура документа описывается в файле 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
— название документа. Отображается в оглавлении над списком всех разделов.name
— имя раздела или группы разделов.href
— относительный путь до файла.items
— группирующий элемент.
Условия видимости разделов
Отдельные разделы можно включать или не включать в документ в зависимости от значений переменных. Для описания условий видимости используется параметр when
.
Доступные операторы сравнения: ==
, !=
, <
, >
, <=
, >=
.
- name: Раздел с условным вхождением
href: path/to/conditional/file.md
when: version == 12
Вставки оглавлений
Вы можете включить в свой документ оглавление другого документа (другой файл toc.yaml
) как подраздел. Для этого используйте параметры:
include
— элемент, который позволяет включить другое оглавление. Должен содержать дочерний элементpath
.path
— путь до оглавления, которое необходимо включить.
Вставка оглавлений позволяет независимо поддерживать отдельные разделы и собирать документ из крупных блоков.
Пример с включением оглавления как раздела
- name: Имя заимствованного блока
include:
path: another/toc.yaml
Пример с включением оглавления без создания раздела
Также есть возможность включать toc.yaml
с добавлением его элементов на тот же уровень оглавления.
toc.yaml
:
items:
- name: Name1
href: file1.md
# Отсутствие поля name у элемента означает, что элементы включаемого оглавления стоит
# добавлять на тот же уровень оглавления, а не как новый раздел
- include: { path: path/to/toc.yaml }
- name: NameX
href: fileX.md
path/to/toc.yaml
:
items:
- name: NameA
href: fileA.md
- name: NameB
href: fileB.md
Результат в оглавлении:
- Name1
- NameA
- NameB
- NameX
mode
include
также может содержать дочерний элемент mode
.
mode
- режим включения оглавления.
Возможные значения: root_merge
, merge
, link
. Значение по умолчанию: root_merge
.
Различия:
merge
иlink
-path
указывается относительно оглавления, в которое происходит включение.root_merge
-path
указывается относительно корня документации.root_merge
иmerge
- все файлы и директории, лежащие рядом с включаемым оглавлением,
копируются в директорию оглавления, в которое происходит включение. Копирование происходит с перезаписью файлов.
Так как при копировании меняется структура проекта, в метаданные файлов добавляетсяsourcePath
с путем до исходного файла.
Это поле используется для ссылки на редактирование страницы.link
- не изменяется структура проекта. Все ссылки включаемого оглавления меняются на ссылки относительно оглавления,
в которое происходит включение.
Скрытые разделы
Чтобы раздел был доступен только по прямой ссылке и не попал в оглавление, укажите параметр hidden
.
- title: Секретный документ
href: secret.md
hidden: true
Для полного исключения скрытых разделов из сборки используйте ключ сборки --remove-hidden-toc-items=true
.