Table of contents

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


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


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

title: Document title
href: index.yaml
  - name: Section name
    href: path/to/
  - name: Section group name
      - name: Section name
        href: path/to/
      - name: Section name
        href: path/to/
  - name: Section name
    href: path/to/
  • 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/
  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
    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
    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.


  - name: Name1

  # 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


  - name: NameA
  - name: NameB

Result in the table of contents:

  • Name1
  • NameA
  • NameB
  • NameX


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:

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


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

List of implemented includers

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
  - name: docs
      path: docs
      includer: sourcedocs
      mode: link


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
  - name: Getting started
  - name: Test topichead
    expanded: true
      - name: Creating a virtual machine
  - name: Initial software configuration
  - name: Operating a virtual machine
  - name: API reference

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

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