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

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

Вставки оглавлений

Вы можете разбить оглавление на несколько файлов и вставить одно оглавление в другое. Когда это пригодится:

  • У вас есть блоки оглавления, которые используются в нескольких документах.
  • У вас большой документ, который проще собирать из нескольких блоков поменьше.

Пример с включением оглавления как раздела

- 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 }

Includers

Доступно включение произвольного контента, но только в случае если includer для этого типа контента имплементирован.

Важно

значение поля includer должно быть названием имплементированного includer'а.

значение поля mode должно быть link или пропущенно(link является дефолтным поведением).

значение поля path должно быть путем до включаемого контента.

Список имплементированных includer'ов

Source Docs

Мы можем включить документацию в формате Source Docs в основной документ.

Пример использования

У нас есть проект документации в папке doc_root.

Положим результат исполнения Source Docs в папку doc_root/doc.

Включим его в документацию внутри doc_root/toc.yaml, указав includer sourcedocs

Поставим ссылку на сгенерированную разводящую в основной в doc_root/index.yaml.

# doc_root/toc.yaml
title: documentation
href: index.yaml
items:
  - name: docs
    include:
      path: docs
      includer: sourcedocs
      mode: link
# doc_root/index.yaml
title: documentation
links:
  - title: docs
    href: docs/

Open API

Мы можем сгенерировать документацию из Open API спецификации и включить её в основную.

Пример использования

У нас есть проект документации в папке doc_root.

Положим спецификацию в doc_root/openapi.yaml.

Включим её внутри doc_root/toc.yaml, указав openapi includer.

Поставим ссылку на сгенерированную разводящую в основной в doc_root/index.yaml.

# doc_root/toc.yaml
title: documentation
href: index.yaml
items:
  - name: docs
    include:
      path: openapi.yaml
      includer: openapi
      mode: link
# doc_root/index.yaml
title: documentation
links:
  - title: openapi
    href: openapi/

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

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

Скрытые разделы

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

- title: Секретный документ
  href: secret.md
  hidden: true

Для полного исключения скрытых разделов из сборки используйте ключ сборки --remove-hidden-toc-items=true.