---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://3y3.dev/en/project/toc.md
  - https://3y3.dev/ru/project/toc.md
  - href: ru/project/toc.md
    type: text/markdown
    title: Markdown version
  - href: ../llms.txt
    type: text/markdown
    title: llms.txt
updatedAt: '2026-07-23T07:10:07.000Z'
---
> **Documentation Index:** Fetch the complete configuration index at https://3y3.dev/ru/llms.txt

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

Структура документа описывается в файле `toc.yaml`. На основе этого файла генерируется оглавление и происходит сборка документа.

{% note warning %}

Файлы, которые не указаны в `toc.yaml`, не обрабатываются при сборке.

{% endnote %}

## Структура {#structure}

Стандартная структура файла `toc.yaml` имеет вид:

```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` — название документа. Отображается в оглавлении над списком всех разделов. Можно скрыть его отображение с помощью настройки ##interface: toc-header## в [файле .yfm](https://3y3.dev/ru/settings.md#toc-header).
* `href` — относительный путь до файла.
* `items` — пункты оглавления.
* `navigation` – секция настроек [расширенной навигации](https://3y3.dev/ru/project/navigation.md).

Каждый пункт оглавления содержит поля:

* `name` — имя раздела или группы разделов.
* `href` — относительный путь до файла.
* `items` — список вложенных пунктов.

Все относительные пути считаются от _расположения_ файла `toc.yaml`, в котором они указаны.

Можно сгруппировать части документации в [несколько отдельных оглавлений](https://3y3.dev/ru/project/toc-multiple.md).

Для упрощения работы с большими оглавлениями и переиспользования блоков поддержана [вставка оглавлений](https://3y3.dev/ru/project/toc-includes.md).

> Смотри также: [Ajv схема файлов оглавления toc.yaml](https://raw.githubusercontent.com/diplodoc-platform/ajv/refs/heads/master/src/json/toc-schema.json)

## Открытие ссылок в новой вкладке {#target}

По умолчанию, все относительные ссылки в оглавлении открываются в текущей вкладке браузера, все абсолютные ссылки – в новой вкладке. Это поведение можно менять с помощью параметра `target`:

* `_self` — ссылка из оглавления будет открываться в текущей вкладке,
* `_blank` — ссылка из оглавления будет открываться в новой вкладке.

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

## Условия видимости разделов {#when}

Отдельные разделы можно включать или не включать в документ в зависимости от значений [переменных](https://3y3.dev/ru/syntax/vars.md). Для описания условий видимости используется параметр `when`.

Доступные операторы сравнения: `==`, `!=`, `<`, `>`, `<=`, `>=`.

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

## Подстановки и условные операторы {#subtitudes}

Название документа поддерживает [подстановки](../syntax/vars#subtitudes) и [условные операторы](../syntax/vars#conditions).

```yaml
title: "{{ title }}"
```

{% note warning %}

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

{% endnote %}

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

По умолчанию все разделы оглавления свернуты. Чтобы важные разделы и страницы в оглавлении всегда были на виду, можно использовать параметр `expanded`:

```yaml
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
```

{% note warning %}

Использовать `expanded` можно только для разделов первого уровня, указание `expanded` в разделах ниже игнорируется.

{% endnote %}

## Labeled-разделы в навигации {#labeled}

Специальные заголовки, которые визуально группируют отдельные пункты в оглавлении.

В файле `toc.yaml` у соответствующего пункта меню укажите атрибут `labeled: true`:

```yaml
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}

Чтобы раздел был доступен только по прямой ссылке и не попал в оглавление, укажите параметр `hidden`.

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

Для полного исключения скрытых разделов из сборки используйте [ключ сборки](https://3y3.dev/ru/tools/docs/settings.md) `--remove-hidden-toc-items=true`.

## Автогенерация оглавления

Для автоматического построения оглавления из списка md-файлов в папке можно использовать [generic-инклюдер](https://3y3.dev/ru/guides/generic.md).