Оглавление документа

Структура документа описывается в файле 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.