Оглавление документа
Структура документа описывается в файле 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
Подстановки и условные операторы
Название документа поддерживает подстановки и условные операторы.
title: "not_var{{ 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
.
Вставки оглавлений
Вы можете разбить оглавление на несколько файлов и вставить одно оглавление в другое. Когда это пригодится:
- У вас есть блоки оглавления, которые используются в нескольких документах.
- У вас большой документ, который проще собирать из нескольких блоков поменьше.
Пример с включением оглавления как раздела
- name: Имя заимствованного блока
include:
path: another/toc.yaml
По умолчанию в path
указывается путь от корня документации. Имя импортируемого файла может быть любым, необязательно toc.yaml
:
- name: Инструкции для Android
include:
path: another/toc_android.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)
Есть несколько режимов, которые задаются в свойстве mode
:
-
root_merge
— этот режим включен по умолчанию. В нём вместе с оглавлением скопируются и все используемые файлы и директории. Допустим, вы импортируете содержание из папки A в содержание, которое лежит в папке B. Тогда при сборке в папку B скопируются все файлы из папки A. Учтите, копирование происходит с перезаписью файлов.Так как при копировании меняется структура проекта, в метаданные новых файлов добавляется
sourcePath
с путем до исходного файла. Это поле используется для ссылки на редактирование страницы. -
merge
— аналогичноroot_merge
, но путь к файлу с оглавлением указывается относительно текущего файла, в котором вы используетеinclude
. -
link
— не изменяется структура проекта. Все ссылки включаемого оглавления меняются на ссылки относительно оглавления, в которое происходит включение.
Пример:
Необходимо указать относительный путь в path
на оглавление, которое импортируется:
items:
- include: { mode: merge, path: ../relative/path/to/toc.yaml }