The document structure is described in the file toc.yaml. It defines how a table of contents is generated and documentation is built.

Warning

Files that are not specified in toc.yaml are not processed during the build.

Structure

The standard toc.yaml file structure looks like the following:

title: Document title
href: index.yaml
items:
- name: Section name
href: path/to/file.md
- name: Section group name
items:
- name: Section name
href: path/to/file.md
- name: Section name
href: path/to/file.md
- name: Section name
href: path/to/file.md

• title: Document name. It's displayed in the table of contents above the list of all sections.
• name: The name of a section or group of sections.
• href: A relative path to the file.
• items: A grouping element.

Section visibility conditions

Individual sections can be included in or excluded from the document, depending on the values of variables. To describe visibility conditions, the when parameter is used.

Possible comparison operators: ==, !=, <, >, <=, >=.

- name: Section with conditional entry
href: path/to/conditional/file.md
when: version == 12


Inserting tables of contents

You can split a table of contents into different files and insert one table of contents into another. Use cases:

• You have table of contents blocks in several documents.
• You have a large document, which is easier to build from smaller blocks.

Example of including a table of contents as a section

- name: Imported block name
include:
path: another/toc.yaml


By default, path specifies the path from the documentation root. The name of the imported file doesn't have to be toc.yaml:

- name: Instructions for Android
include:
path: another/toc_android.yaml


Example of including a table of contents without creating a section

You can also include toc.yaml with its elements in the same level of the table of contents.

toc.yaml:

items:
- name: Name1
href: file1.md

# If an element doesn't have a name field, it means that elements of the included table of contents must be
# added to the same table of contents level, not as a new section
- 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

Different modes that can be set in the mode property:

• root_merge: Enabled by default. This copies the table of contents along with all of the files and directories it uses. Let's say that you're importing the contents from folder A into the contents in folder B. All of the files from folder A will be copied to folder B during the build. Note that copying overwrites files.

The copying process changes the project structure, and sourcePath is added to the new files' metadata with the path to the source file. This field is used for the link to edit the page.

• merge: Similar to root_merge, but the path to the table of contents file is specified relative to the current file where you are using include.

• link: The project structure doesn't change. All of the included table of contents' links are changed to links relative to the table of contents where it's included.

For example, let's say you want to specify a relative path in path to the table of contents you are importing. Do it like this:

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


Includers

You can include any content, but only if the includer for this type of content is implemented.

Usage example

Let's say we have a documentation project in the doc_root folder.

We can put the SourceDocs results into the doc_root/doc folder.

To include them in the documentation inside doc_root/toc.yaml, add includer and the link to the generated section page to the main doc_root/index.yaml.

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


Warning

includer must be the name of the implemented includer.

mode must be link or omitted(link is the default).

path must be the path to the included content.

# doc_root/index.yaml
title: documentation
- title: docs
href: docs/


Section expansion

By default, all table of contents sections are hidden. You can change it by adding expanded:

title: Yandex Cloud Marketplace
items:
- name: Getting started
href: index.md
- name: Test topichead
expanded: true
items:
- name: Creating a virtual machine
href: create.md
- name: Initial software configuration
href: setup.md
- name: Operating a virtual machine
href: operate.md
- name: API reference
href: guide.md


You can only use expanded for first-level sections. In lower sections, expanded will be ignored.
Use it to make important sections and pages in the table of contents always visible.

Hidden sections

To make a section accessible only by direct link and excluded it from the table of contents, add the hidden parameter.

- title: Secret document
href: secret.md
hidden: true


To completely exclude hidden sections from the build, use the build key --remove-hidden-toc-items=true.