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

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

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

Включение оглавления как раздела

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

• root_merge — этот режим включен по умолчанию. В нём вместе с оглавлением скопируются и все используемые файлы и директории. Допустим, вы импортируете содержание из папки A в содержание, которое лежит в папке B. Тогда при сборке в папку B скопируются все файлы из папки A. Обратите внимание, копирование происходит с перезаписью файлов.

  Так как при копировании меняется структура проекта, в метаданные новых файлов добавляется sourcePath с путем до исходного файла. Это поле используется для ссылки на редактирование страницы.

• merge — аналогично root_merge, но путь к файлу с оглавлением указывается относительно текущего файла, в котором вы используете include.

• link — не изменяется структура проекта. Все ссылки включаемого оглавления меняются на ссылки относительно оглавления, в которое происходит включение.

Пример:
Необходимо указать относительный путь к path на оглавление, которое импортируется:

items:
  - include: { mode: merge, path: ../relative/path/to/toc.yaml }

Вставка произвольного контента

С помощью параметра includers вы можете вставлять в документацию произвольный контент.