Document table of contents

The document structure is described in the file toc.yaml. Based on this file, the table of contents is generated and the document is assembled.

Structure

The standard structure of the toc.yaml file is as follows:

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

At the root:

• title — the document title. It is displayed in the table of contents above the list of all sections. You can hide it using the interface: toc-header setting in the .yfm file.
• href — the relative path to the file.
• items — table of contents items.
• navigation — a settings section for extended navigation.

Each table of contents item contains the following fields:

• name — the name of a section or group of sections. For a section that links to an article, the field can be omitted, see name from the article heading.
• href — the relative path to the file.
• items — a list of nested items.

All relative paths are calculated from the location of the toc.yaml file in which they are specified.

Section name from the article heading

If a section with an href to an md file has no name field, or the field is set to {#T}, the build takes the name from the first-level heading of that article, including a heading that comes from an include. If the article has no first-level heading, the file name without the extension is used.

items:
  - href: overview.md
  - name: "{#T}"
    href: setup.md
  - name: API reference
    href: api.md

This way the item name in the table of contents always matches the article heading and is edited in one place. It also helps with translations: such an item does not need to be translated in toc.yaml, each language gets the article heading in that language. The rule works the same way as heading substitution in links.

You can group parts of the documentation into multiple separate tables of contents.

To simplify working with large tables of contents and reuse blocks, inserting tables of contents is supported.

See also: Ajv schema for toc.yaml table of contents files

Opening links in a new tab

By default, all relative links in the table of contents open in the current browser tab, and all absolute links open in a new tab. This behavior can be changed using the target parameter:

• _self — a link from the table of contents will open in the current tab,
• _blank — a link from the table of contents will open in a new tab.

- name: Абсолютная ссылка
  href: https://github.com
  target: _self

Section visibility conditions

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

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

- name: Раздел с условным вхождением
  href: path/to/conditional/file.md
  when: version == 12

Substitutions and conditional operators

The document title supports substitutions and conditional operators.

title: "{{ title }}"

Configuring section expansion

By default, all sections of the table of contents are collapsed. To keep important sections and pages always visible in the table of contents, you can use the expanded parameter:

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

Labeled sections in navigation

Special headings that visually group individual items in the table of contents.

In the toc.yaml file, specify the labeled: true attribute for the corresponding menu item:

title: Имя документа
href: index.yaml
items:
  - name: Имя раздела
    labeled: true
    href: path/to/file.md
  - name: Имя группы разделов
    labeled: true
    items:
      - name: Имя раздела
        href: path/to/file.md
      - name: Имя раздела
        href: path/to/file.md
  - name: Имя раздела
    labeled: true
    href: path/to/file.md

Hidden sections

To make a section accessible only via a direct link and exclude it from the table of contents, specify the hidden parameter.

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

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

Auto-generation of the table of contents

To automatically build a table of contents from a list of md files in a folder, you can use the generic includer.