diplodoc-platform · bloodmike · Apr 3, 2026 · Apr 3, 2026
@@ -16,7 +16,6 @@ noindex: true
 - [Unarchive инклюдер](./project/toc.md#includers-unarchive).
 - [Source Docs инклюдер](./project/toc.md#includers-source-docs).
 
-
 ## Ноябрь 2022
 
 ### yfm-docs

@@ -80,7 +80,7 @@ tocHooks.Resolved.tapPromise('MyProcessor', async (toc, tocPath) => {
 
 ### Included
 
-Хук для обработки ToC после его включения через ##[include](../../../project/toc.md#includes)##.
+Хук для обработки ToC после его включения через ##[include](../../../project/toc-includes.md)##.
 
 ```typescript
 tocHooks.Included.tapPromise('MyProcessor', async (toc, tocPath, includeInfo) => {

@@ -1,18 +1,12 @@
 # Generic
 
-{% note info %}
+Generic — это встроенный [инклюдер](*includer) для включения Markdown-файлов в структуру документации без ручного перечисления каждого заголовка в `toc.yaml`.
 
-Generic includer включен по умолчанию.
-
-{% endnote %}
-
-Generic — это встроенный [includer](*includer), который позволяет автоматически включать Markdown-файлы в структуру документации без ручного перечисления каждого заголовка в `toc.yaml`.
-
-## Пример использования
+## Пример использования {#example}
 
 Документация находится в директории `doc_root`. Сгенерированный контент нужно положить в директорию `doc_root/gen_docs`.
 
-Добавим в `doc_root/toc.yaml` generic includer.
+Добавим в `doc_root/toc.yaml` generic-инклюдер.
 
 ```yaml
 # doc_root/toc.yaml
@@ -22,15 +16,15 @@ items:
   - name: docs
     include:
       path: gen_docs # путь к директории с .md файлами для сгененированного контента
-      includers: # подключение generic includer
+      includers: # подключение generic-инклюдер
         - name: generic
           autotitle: true   # опционально: при false, проставляет в структуру название md-файлов, при true — название заголовков, по умолчанию true
       mode: link
 ```
 
 Укажем сгенерированную страницу на [разводящей](*Разводящая_страница) в `doc_root/index.yaml`.
 
-## Параметры
+## Параметры {#settings}
 
 | Параметр | Тип | Значение по умолчанию | Описание |
 | --- | --- | --- | --- |
@@ -39,7 +33,7 @@ items:
 
 ## Кликабельные разделы с `linkIndex` {#link-index}
 
-По умолчанию generic includer формирует разделы на основе названий директорий. Элемент раздела является только раскрывающимся — при нажатии он сворачивает или разворачивает список дочерних страниц, а `index.md` становится обычным дочерним элементом.
+По умолчанию generic-инклюдер формирует разделы на основе названий директорий. Элемент раздела является только раскрывающимся — при нажатии он сворачивает или разворачивает список дочерних страниц, а `index.md` становится обычным дочерним элементом.
 
 С опцией `linkIndex: true` поведение меняется: файл `index.md` внутри поддиректории становится ссылкой (`href`) родительского элемента навигации. При нажатии на раздел открывается `index.md`, а список дочерних страниц разворачивается с помощью стрелки.
 

@@ -1,41 +1,12 @@
-# Вставка произвольного контента (Includers)
+# Вставка произвольного контента (includers)
 
-Вы можете включить в оглавление произвольный контент через `includers`, но только в случае если `includer` для этого типа контента имплементирован. Список имплементированных инклюдеров можно посмотреть [ниже](#implement-includers).
+Можно включить в документацию произвольный контент через инклюдеры (от английского `includers`) — специальный механизм расширения документационного проекта на этапе сборки дополнительными файлами.
 
-Возможные способы указания инклюдеров:
+## Подключение {#config}
 
-- массив `includer`-объектов в поле `includers`;
+Инклюдеры подключаются в поле `includers` у пункта оглавления с параметром `include`:
 
-- `includer`-объект в поле `includer` (_в процессе деприкации в пользу `includers` поля_).
-
-**Требования к `include`:**
-
-1. `include` должен иметь поле `path`, куда контент будет включен.
-
-2. поле `path` должно быть **путем, куда будет включен контент**.
-
-3. свойство `mode` должно иметь значение `link или пропущенно, `link является поведением по умолчанию.
-
-**Требования к `includers`:**
-
-`includers` должен быть массивом includer-объектов, которые будут запущенны в указанном порядке.
-
-**Требования к `includer`:**
-
-Параметры между includer-объектами разные, но имя `includer` является обязательным параметром.
-
-`name` указывает имя инклюдера, который запустится.
-
-
-#### Пример использования
-
-Абстрактный пример использования инклюдеров
-
-_Уточненный пример смотрите в разделе соответствуещего инклюдера для конкретного примера использования._
-
-```
-# toc.yaml
-...
+```yaml
 items:
   - name: <item-name>
     include:
@@ -46,12 +17,20 @@ items:
         - name: <name-of-the-second-includer>
         - name: <name-of-the-third-includer>
       mode: link
-...
 ```
 
-## Список имплементированных инклюдеров {#implement-includers}
+1. Объект `include` должен иметь поле `path` с путем, **откуда** контент будет включен.
+
+2. Параметр `mode` должен иметь значение `link` или быть пропущен, `link` является значением по умолчанию.
+
+3. Параметр `includers` должен содержать список _includer-объектов_, которые будут вызваны последовательно в указанном порядке. 
+
+4. Каждый _includer-объект_ должен содержать поле `name` с типом инклюдера:
+
+    - `generic` — [вставка произвольных Markdown-файлов в структуру проекта](generic.md);
+
+    - `openapi` — [автогенерация статей на основе OpenAPI-спецификаций](openapi.md);
+
+    - `unarchive` — [распаковка tar-файла перед выполнением других инклюдеров](unarchive.md).
 
-- [Generic](generic.md);
-- [Open API](openapi.md);
-- [Unarchive](unarchive.md);
-- [Source Docs](source-docs.md) (_в процессе деприкации в пользу generic инклюдера_).
+5. У разных типов инклюдеров могут быть собственные параметры, которые указываются в _includer-объекте_.
@@ -8,13 +8,13 @@ Openapi-инклюдер требует разрешение на использ
 
 {% endnote %}
 
-## Требования к OpenAPI-спецификации
+## Требования к OpenAPI-спецификации {#requirements}
 
 - Версия используемой спецификации не ниже 3.Х.
 - Допускается использование только операторов `oneOf` и `allOf`.
 - Ограничения на использование базового функционала не накладываются.
 
-#### Пример использования
+#### Пример использования {#example}
 
 1. Документационный проект лежит в директории `doc_root`.
 

@@ -48,7 +48,7 @@
 
     {% endcut %}
 
-  * [Вставки оглавлений](../../project/toc.md#includes) — блоки оглавления, которые вставляются в основное оглавление.
+  * [Вставки оглавлений](../../project/toc-includes.md) — блоки оглавления, которые вставляются в основное оглавление.
 
     {% cut "Пример" %}
 

@@ -2,7 +2,7 @@
 
 Вы можете включить документацию в формате [Source Docs](https://github.com/SourceDocs/SourceDocs) в основной документ.
 
-{% note warning %}
+{% note alert %}
 
 sourcedocs-инклюдер находится в процессе деприкации в пользу [generic-инклюдера](generic.md).
 

@@ -1,14 +1,6 @@
-# Документационный проект
+# Структура проекта
 
-YFM позволяет создавать и поддерживать документационные проекты.
-
-**Пример**: [документация Yandex.Cloud](https://github.com/yandex-cloud/docs).
-
-## Структура проекта {#structure}
-
-Базовый проект включает:
-- [Файл оглавления](./toc.md)
-- Файлы с контентом
+Базовый проект включает [файл оглавления](./toc.md) и файлы с контентом.
 
 Рекомендуемые дополнительные элементы:
 - [Разводящая страница](./leading-page.md)

@@ -1,17 +1,14 @@
 # Разводящая страница
 
-Для быстрой навигации по документу вы можете оформить корневую страницу в виде сетки с ссылками на основные разделы `index.yaml`.
+Для быстрой навигации по документу вы можете оформить страницу в виде сетки со ссылками на основные разделы.
 
-Для небольших документов допустимо использовать упрощенный вариант — обычную страницу с описанием и ссылками `index.md`.
-
-Пример:
-Оформление разводящей страницы [документации сервиса Yandex Compute Cloud](https://cloud.yandex.ru/docs/compute/).
+Пример: оформление разводящей страницы [документации сервиса Yandex Compute Cloud](https://cloud.yandex.ru/docs/compute/).
 
 ![Пример разводящей страницы](../_images/leading.png)
 
 ## Структура {#structure}
 
-Стандартная структура файла разводящей страницы `index.yaml` имеет вид:
+Стандартная структура yaml-файла разводящей страницы имеет вид:
 
 ```yaml
 title: Имя документа
@@ -35,6 +32,8 @@ links:
     * `description`— описание раздела.
     * `href` — относительный путь до файла без указания расширения.
 
+Описания документа и разделов **не поддерживают** markdown-разметку.
+
 ## Условия видимости элементов {#when}
 
 Отдельные разделы можно отображать или не отображать на разводящей странице в зависимости от значений [переменных](../syntax/vars.md). Для описания условий видимости используется параметр `when`.

@@ -0,0 +1,81 @@
+# Вставка оглавлений
+
+Вы можете разбить оглавление на несколько файлов и вставить одно оглавление в другое. Когда это пригодится:
+* У вас есть блоки оглавления, которые используются в нескольких документах.
+* У вас большой документ, который проще собирать из нескольких блоков поменьше.
+
+## Включение оглавления как раздела {#as-section}
+
+```yaml
+- name: Имя заимствованного блока
+  include:
+    path: another/toc.yaml
+```
+
+По умолчанию в `path` указывается путь от корня документации. Имя импортируемого файла может быть любым, необязательно `toc.yaml`:
+
+```yaml
+- name: Инструкции для Android
+  include:
+    path: another/toc_android.yaml
+```
+
+## Включение оглавления без создания раздела {#as-pages}
+
+Вы можете включать `toc.yaml` с добавлением его элементов на тот же уровень оглавления.
+
+`toc.yaml`:
+
+```yaml
+items:
+  - name: Name1
+    href: file1.md
+
+  # Отсутствие поля name у элемента означает, что элементы включаемого оглавления стоит
+  # добавлять на тот же уровень оглавления, а не как новый раздел
+  - include: { path: path/to/toc.yaml }
+
+  - name: NameX
+    href: fileX.md
+```
+`path/to/toc.yaml`:
+
+```yaml
+items:
+  - name: NameA
+    href: fileA.md
+  - name: NameB
+    href: fileB.md
+```
+Результат в оглавлении:
+
+```
+- Name1
+- NameA
+- NameB
+- NameX
+```
+
+
+## Режимы вставки оглавлений {#include-mode}
+
+Есть несколько режимов, которые задаются в свойстве `mode`:
+
+* `root_merge` — этот режим включен по умолчанию. В нём вместе с оглавлением скопируются и все используемые файлы и директории. Допустим, вы импортируете содержание из папки A в содержание, которое лежит в папке B. Тогда при сборке в папку B скопируются все файлы из папки A. Обратите внимание, копирование происходит с перезаписью файлов.
+
+  Так как при копировании меняется структура проекта, в метаданные новых файлов добавляется `sourcePath` с путем до исходного файла. Это поле используется для ссылки на редактирование страницы.
+
+* `merge` — аналогично `root_merge`, но путь к файлу с оглавлением указывается относительно текущего файла, в котором вы используете `include`.
+* `link` — не изменяется структура проекта. Все ссылки включаемого оглавления меняются на ссылки относительно оглавления, в которое происходит включение.
+
+**Пример:**
+Необходимо указать относительный путь к `path` на оглавление, которое импортируется:
+
+```yaml
+items:
+  - include: { mode: merge, path: ../relative/path/to/toc.yaml }
+```
+
+## Вставка произвольного контента {#includers}
+
+С помощью параметра `includers` вы можете вставлять в документацию [произвольный контент](../guides/includers.md).