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

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

Каждый пункт оглавления содержит поля:

• name — имя раздела или группы разделов. Для раздела со ссылкой на статью поле можно не указывать, см. имя из заголовка статьи.
• href — относительный путь до файла.
• items — список вложенных пунктов.

Все относительные пути считаются от расположения файла toc.yaml, в котором они указаны.

Имя раздела из заголовка статьи

Если у раздела с href на md-файл не указано поле name или в нём стоит {#T}, при сборке имя подставляется из заголовка первого уровня этой статьи, в том числе когда заголовок приходит из вставки. Если заголовка первого уровня в статье нет, используется имя файла без расширения.

items:
  - href: overview.md
  - name: "{#T}"
    href: setup.md
  - name: Справочник API
    href: api.md

Так имя пункта в оглавлении всегда совпадает с заголовком статьи и редактируется в одном месте. Это удобно и для переводов: такой пункт не нужно переводить в toc.yaml, в каждом языке подставится заголовок статьи на этом языке. Правило работает так же, как подстановка заголовков в ссылках.

Можно сгруппировать части документации в несколько отдельных оглавлений.

Для упрощения работы с большими оглавлениями и переиспользования блоков поддержана вставка оглавлений.

Смотри также: Ajv схема файлов оглавления toc.yaml

Открытие ссылок в новой вкладке

По умолчанию, все относительные ссылки в оглавлении открываются в текущей вкладке браузера, все абсолютные ссылки – в новой вкладке. Это поведение можно менять с помощью параметра target:

• _self — ссылка из оглавления будет открываться в текущей вкладке,
• _blank — ссылка из оглавления будет открываться в новой вкладке.

- name: Абсолютная ссылка
  href: https://github.com
  target: _self

Условия видимости разделов

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

Доступные операторы сравнения: ==, !=, <, >, <=, >=.

- name: Раздел с условным вхождением
  href: path/to/conditional/file.md
  when: version == 12

Подстановки и условные операторы

Название документа поддерживает подстановки и условные операторы.

title: "{{ title }}"

Настройка раскрытия разделов

По умолчанию все разделы оглавления свернуты. Чтобы важные разделы и страницы в оглавлении всегда были на виду, можно использовать параметр 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

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.

Автогенерация оглавления

Для автоматического построения оглавления из списка md-файлов в папке можно использовать generic-инклюдер.