From 3dcff8a6b80a5034b49b06e4136883150553a194 Mon Sep 17 00:00:00 2001 From: Mihail Koshkin Date: Fri, 3 Apr 2026 17:14:29 +0300 Subject: [PATCH] update toc/toc-includes/includers info --- ru/changelog.md | 1 - ru/dev/extensions/services/toc-service.md | 2 +- ru/guides/generic.md | 18 ++--- ru/guides/includers.md | 59 +++++--------- ru/guides/openapi.md | 4 +- ru/guides/single-source/index.md | 2 +- ru/guides/source-docs.md | 2 +- ru/project/index.md | 12 +-- ru/project/leading-page.md | 11 ++- ru/project/toc-includes.md | 81 +++++++++++++++++++ ru/project/toc.md | 94 +++-------------------- ru/settings.md | 2 +- ru/toc.yaml | 22 +++--- ru/tools/docs/build.md | 2 +- 14 files changed, 141 insertions(+), 171 deletions(-) create mode 100644 ru/project/toc-includes.md diff --git a/ru/changelog.md b/ru/changelog.md index 37c20e59..db104da4 100644 --- a/ru/changelog.md +++ b/ru/changelog.md @@ -16,7 +16,6 @@ noindex: true - [Unarchive инклюдер](./project/toc.md#includers-unarchive). - [Source Docs инклюдер](./project/toc.md#includers-source-docs). - ## Ноябрь 2022 ### yfm-docs diff --git a/ru/dev/extensions/services/toc-service.md b/ru/dev/extensions/services/toc-service.md index cb4e37db..eff6f616 100644 --- a/ru/dev/extensions/services/toc-service.md +++ b/ru/dev/extensions/services/toc-service.md @@ -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) => { diff --git a/ru/guides/generic.md b/ru/guides/generic.md index e488bcfd..75b16783 100644 --- a/ru/guides/generic.md +++ b/ru/guides/generic.md @@ -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,7 +16,7 @@ items: - name: docs include: path: gen_docs # путь к директории с .md файлами для сгененированного контента - includers: # подключение generic includer + includers: # подключение generic-инклюдер - name: generic autotitle: true # опционально: при false, проставляет в структуру название md-файлов, при true — название заголовков, по умолчанию true mode: link @@ -30,7 +24,7 @@ items: Укажем сгенерированную страницу на [разводящей](*Разводящая_страница) в `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`, а список дочерних страниц разворачивается с помощью стрелки. diff --git a/ru/guides/includers.md b/ru/guides/includers.md index 8d491701..bb20adbb 100644 --- a/ru/guides/includers.md +++ b/ru/guides/includers.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: include: @@ -46,12 +17,20 @@ items: - name: - name: 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 инклюдера_). \ No newline at end of file +5. У разных типов инклюдеров могут быть собственные параметры, которые указываются в _includer-объекте_. diff --git a/ru/guides/openapi.md b/ru/guides/openapi.md index 5c2380e5..551f5554 100644 --- a/ru/guides/openapi.md +++ b/ru/guides/openapi.md @@ -8,13 +8,13 @@ Openapi-инклюдер требует разрешение на использ {% endnote %} -## Требования к OpenAPI-спецификации +## Требования к OpenAPI-спецификации {#requirements} - Версия используемой спецификации не ниже 3.Х. - Допускается использование только операторов `oneOf` и `allOf`. - Ограничения на использование базового функционала не накладываются. -#### Пример использования +#### Пример использования {#example} 1. Документационный проект лежит в директории `doc_root`. diff --git a/ru/guides/single-source/index.md b/ru/guides/single-source/index.md index a300ebe7..91b3fbae 100644 --- a/ru/guides/single-source/index.md +++ b/ru/guides/single-source/index.md @@ -48,7 +48,7 @@ {% endcut %} - * [Вставки оглавлений](../../project/toc.md#includes) — блоки оглавления, которые вставляются в основное оглавление. + * [Вставки оглавлений](../../project/toc-includes.md) — блоки оглавления, которые вставляются в основное оглавление. {% cut "Пример" %} diff --git a/ru/guides/source-docs.md b/ru/guides/source-docs.md index 106c35d9..08646d9c 100644 --- a/ru/guides/source-docs.md +++ b/ru/guides/source-docs.md @@ -2,7 +2,7 @@ Вы можете включить документацию в формате [Source Docs](https://github.com/SourceDocs/SourceDocs) в основной документ. -{% note warning %} +{% note alert %} sourcedocs-инклюдер находится в процессе деприкации в пользу [generic-инклюдера](generic.md). diff --git a/ru/project/index.md b/ru/project/index.md index a18414c1..90859e28 100644 --- a/ru/project/index.md +++ b/ru/project/index.md @@ -1,14 +1,6 @@ -# Документационный проект +# Структура проекта -YFM позволяет создавать и поддерживать документационные проекты. - -**Пример**: [документация Yandex.Cloud](https://github.com/yandex-cloud/docs). - -## Структура проекта {#structure} - -Базовый проект включает: -- [Файл оглавления](./toc.md) -- Файлы с контентом +Базовый проект включает [файл оглавления](./toc.md) и файлы с контентом. Рекомендуемые дополнительные элементы: - [Разводящая страница](./leading-page.md) diff --git a/ru/project/leading-page.md b/ru/project/leading-page.md index 063c9408..c2ac2543 100644 --- a/ru/project/leading-page.md +++ b/ru/project/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`. diff --git a/ru/project/toc-includes.md b/ru/project/toc-includes.md new file mode 100644 index 00000000..ef8fa060 --- /dev/null +++ b/ru/project/toc-includes.md @@ -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). \ No newline at end of file diff --git a/ru/project/toc.md b/ru/project/toc.md index 70fa2a5f..5e658809 100644 --- a/ru/project/toc.md +++ b/ru/project/toc.md @@ -28,10 +28,17 @@ items: href: path/to/file.md ``` -* `title` — название документа. Отображается в оглавлении над списком всех разделов. +В корне: +* `title` — название документа. Отображается в оглавлении над списком всех разделов. Можно скрыть его отображение с помощью настройки ##interface: toc-header## в [файле .yfm](../settings.md#toc-header). +* `href` — относительный путь до файла. +* `items` — пункты оглавления. + +Каждый пункт оглавления содержит поля: * `name` — имя раздела или группы разделов. * `href` — относительный путь до файла. -* `items` — группирующий элемент. +* `items` — список вложенных пунктов. + +Для упрощения работы с большими оглавлениями и переиспользования блоков поддержана [вставка оглавлений](./toc-includes.md). ## Условия видимости разделов {#when} @@ -68,7 +75,7 @@ title: Yandex Cloud Marketplace items: - name: Начало работы href: index.md - - name: Тестовый топикхед + - name: Основы expanded: true items: - name: Создание виртуальной машины @@ -123,83 +130,4 @@ items: hidden: true ``` -Для полного исключения скрытых разделов из сборки используйте [ключ сборки](../tools/docs/settings.md) `--remove-hidden-toc-items=true`. - - -## Вставки оглавлений {#includes} - -Вы можете разбить оглавление на несколько файлов и вставить одно оглавление в другое. Когда это пригодится: -* У вас есть блоки оглавления, которые используются в нескольких документах. -* У вас большой документ, который проще собирать из нескольких блоков поменьше. - -### Пример с включением оглавления как раздела {#include-as-section} - -```yaml -- name: Имя заимствованного блока - include: - path: another/toc.yaml -``` - -По умолчанию в `path` указывается путь от корня документации. Имя импортируемого файла может быть любым, необязательно `toc.yaml`: - -```yaml -- name: Инструкции для Android - include: - path: another/toc_android.yaml -``` - -### Пример с включением оглавления без создания раздела {#include-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 -``` - - -### Режимы вставки оглавлений (mode) {#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 } -``` +Для полного исключения скрытых разделов из сборки используйте [ключ сборки](../tools/docs/settings.md) `--remove-hidden-toc-items=true`. \ No newline at end of file diff --git a/ru/settings.md b/ru/settings.md index 00213ef5..d7cec630 100644 --- a/ru/settings.md +++ b/ru/settings.md @@ -252,7 +252,7 @@ extensions: || `toc` | Скрывает оглавление (Table of contents, ToC). Если не указан, ToC считается включенным. | `bool` `true` || -|| `toc-header` | Скрывает заголовок в ToC. Если не указан, заголовок считается включенным. | `bool` +|| `toc-header` {#toc-header} | Скрывает заголовок в ToC. Если не указан, заголовок считается включенным. | `bool` `true` || || `feedback` | Скрывает фидбэк в конце страницы. Если не указан, фидбэк включенным. | `bool` diff --git a/ru/toc.yaml b/ru/toc.yaml index 0aba0d22..c0fcc3f0 100644 --- a/ru/toc.yaml +++ b/ru/toc.yaml @@ -108,6 +108,8 @@ items: href: project/pc-example2.yaml - name: Пример 3 (fullScreen mode) href: project/pc-example3.yaml + - name: Разводящая страница + href: project/leading-page.md - name: Диаграммы href: custom-plugins/mermaid.md items: @@ -115,21 +117,21 @@ items: href: custom-plugins/mermaid-info.md - name: Организация контента items: - - name: Обзор + - name: Структура проекта href: project/index.md - name: Оглавление href: project/toc.md items: - - name: Оглавление на странице документации - href: project/minitoc.md + - name: Вставка оглавлений + href: project/toc-includes.md - name: Расширенная навигация href: project/navigation.md - - name: Разводящая страница - href: project/leading-page.md - - name: Метаданные - href: project/meta.md - name: Редиректы href: project/redirects.md + - name: Метаданные + href: project/meta.md + - name: Оглавление на странице документации + href: project/minitoc.md - name: Конфигурация проекта labeled: true items: @@ -164,11 +166,6 @@ items: - name: Внесение изменений hidden: true href: contribution.md -# - name: Настройка внешнего вида -# labeled: true -# items: - #- name: Темизация - # href: style/theme.md - name: Практические руководства labeled: true items: @@ -192,6 +189,7 @@ items: href: guides/unarchive.md - name: Source Docs href: guides/source-docs.md + hidden: true - name: Content Security Policy (CSP) href: guides/csp.md - name: Настройка версионирования документации diff --git a/ru/tools/docs/build.md b/ru/tools/docs/build.md index 083ccbfb..c5ffac7d 100644 --- a/ru/tools/docs/build.md +++ b/ru/tools/docs/build.md @@ -24,7 +24,7 @@ yfm -o ./output-folder Вы можете выполнить промежуточную сборку YFM в YFM. Для этого при выполнении команды укажите ключ запуска `--output-format=md`. При сборке в YFM выполняются: -* [вставки](../../project/toc.md#includes) и [проверки условия видимости разделов](../../project/toc.md#when) в файлах оглавлений; +* [вставки](../../project/toc-includes.md) и [проверки условия видимости разделов](../../project/toc.md#when) в файлах оглавлений; * [проверки условия отображения контента](../../syntax/vars.md#conditions) на страницах документа; * [подстановки переменных](../../syntax/vars.md#subtitudes), если указан параметр `apply-presets`; * [инлайнинг SVG-изображений](../../syntax/media.md#img-inline);