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

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

Важно

Если значение начинается с подстановки, всегда заключайте его в кавычки. Без них значение обрабатывается как JSON, встроенный в YAML, что может привести к ошибкам сборки, например TypeError: str.replace is not a function.

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

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

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

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

- 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

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

Возможные способы указания инклюдеров:

  • массив includer объектов в поле includers

  • includer объект в includer поле. в процессе деприкации в пользу includers поля

требования к include

include должен иметь path куда контент будет включен

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

mode должен быть link или пропущенно, link является дефолтным поведением

требования к includers

includers должен быть массивом includer объектов, которые будут запущенны в указанном порядке

требования к includer

параметры между инклюдер объектами разные, но одним обязательным параметром будет имя includerа.

name указывает имя инклюдера который запустится

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

Абстрактный пример использования инклюдеров

смотри секцию соответствуещего инклюдера для конкретного примера использования

# toc.yaml
...
items:
  - name: <item-name>
    include:
      path: <path-where-to-include>
      includers:
        - name: <name-of-the-first-includer>
          <includer-parameter>: <includer-parameter-value>
        - name: <name-of-the-second-includer>
        - name: <name-of-the-third-includer>
      mode: link
...

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

Generic

Вы можете сгенерировать документацию в markdown формате любой утилитой и включить её в основную документацию

Инклюдер сгенерирует по ней оглавление и включит контент в документацию

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

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

Положим сгенерированный контент в папку doc_root/docs.

Включим этот контент с помощью инклюдера в doc_root/toc.yaml.

Подключим разводящую в doc_root/index.yaml.

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

Open API

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

Важно

openapi инклюдер требует разрешение на использование HTML в документации

выставите allowHTML на true внутри .yfm конфигурации

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

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

Положим спецификацию open API по пути doc_root/openapi.yaml.

Теперь нам нужно включить её в doc_root/toc.yaml с помощью openapi инклюдера.

Подключим разводящую в doc_root/index.yaml.

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

Unarchive

Мы можем использовать unarchive инклюдер чтобы распаковать tarball перед тем как применять другие инклюдеры
к контенту внутри него, например generic инклюдер

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

Скажем у нас есть docs.tar в корне проекта по пути doc_root/docs.tar.

Внутри docs.tar находится контент который мы хотим включить используя generic инклюдер.

Тогда нам нужно применить цепь инклюдеров(unarchive -> generic) для достижения нащих целей.

# doc_root/toc.yaml
title: documentation
href: index.yaml
items:
...
   - name: multiple
     include:
       path: multiple
       mode: link
       includers:
         # run unarchive includer
         - name: unarchive
           # specify tarball you want to unpack as input parameter
           input: docs.tar
           # specify output path where tarball content is going to be unpacked
           output: unpacked
         # run generic includer
         - name: generic
           # specify path from unarchive includers output field as input path
           input: unpacked
# doc_root/index.yaml
title: documentation
links:
  - title: openapi
    href: openapi/

Source Docs

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

Важно

Source Docs инклюдер находится в процессе деприкации в пользу Generic Инклюдера

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

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

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

Включим его в документацию внутри 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/

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

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