Создание кастомизированной документации по YDB

Содержимое подкаталога core подключается в разные окружения сборки документации как библиотека, для создания кастомизированной документации.

Подкаталог overlay предназначен для кастомизирующего контента, и для OpenSource сборки является техническим, так как OpenSource сборка не содержит кастомизаций ядра.

Прокси-статьи

Файл со статьей в core никогда не содержит контента непосредственно, а только одну или несколько инструкций include блоков этого контента, размещенных в подкаталоге _includes. В результате, замена этого файла в overlay не приводит к необходимости копирования контента, но позволяет сделать следующие виды его адаптации:

• Добавить дополнительный контент в начало или конец статьи
• Вставить дополнительный контент между директивами include
• Убрать из сборки часть контента исходной статьи, удалив соответствующую директиву include

Инструкции по оформлению статей в core и overlay приведены в Руководстве по созданию контента - Статьи.

TOC (Table of Contents) - содержание

TOC в документации YDB собирается из множества файлов, размещенных в директориях со статьями, которые иерархически включаются друг в друга директивой include. В результате каждый из этих файлов может быть переопределен по отдельности в адаптированной документации.

Как и для статей, для файлов TOC применяется подход с прокси, со следующей реализацией:

1. Файл с пунктами меню для core называется toc_i.yaml. Он никогда не переопределяется в overlay.
2. Рядом с файлом toc_i.yaml в core находится файл toc_p.yaml, содержащий ссылку на toc_i.yaml, и предназначенный для переопределения в overlay.
3. Включение TOC других разделов делается ссылкой на файл toc_p.yaml.
4. Если в некоторой директории не требуется корректировать содержимое TOC, то никакие файлы toc* в overlay не создаются, что приводит к использованию toc_p --> toc_i из core при сборке.
5. Если в некоторой директории требуется скорректировать содержимое toc, то в overlay создается файл toc_p.yaml, в контент которого включается существовавший в core - include: { mode: link, path: toc_i.yaml }, а выше или ниже -- дополнительные пункты для адаптированной сборки.

Хорошей практикой является исключение из toc_i.yaml пункта "Обзор" и включение его непосредственно в toc_p.yaml. Данная статья обязана быть первой в каждом подменю, и всегда имеет одно имя статьи (index.md). Включение отдельным пунктом в toc_p позволяет добавить новые статьи в адаптированной документации перед статьями из core, но с сохранением "Обзор" на первом месте:

toc_p.yaml в некотором корпоративном overlay:

items:
- name: Обзор
  href: index.md
- name: Роли сотрудников
  href: corp_roles.md
- include: { mode: link, path: toc_i.yaml }
- name: Корпоративная авторизация
  href: corp_auth.md

Как и для статей, в core может быть заготовлено несколько файлов toc_i*.yaml, включаемых в toc_p отдельными include.

В корневом каталоге также есть пара файлов toc_i и toc_p, представляющих верхний уровень оглавления.

Так как включение файлов производится ссылками на них из родительского toc, то имя файла на самом деле технически может быть любым, и описанное выше -- только соглашение о наименованиях. Но есть один запрет:

Единственное исключение -- это начальный toc.yaml, который размещается в корне сборки документации, и всегда содержит команду копирования содержимого core и перехода к обработке TOC в core: include: { mode: merge, path: core/toc_m.yaml }.

Инструкции по оформлению TOC в core и overlay приведены в Руководстве по созданию контента - TOC.