Создание кастомизированной документации по 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 не может быть toc.yaml, так как инструмент сборки ищет файлы с такими именами по всем подкаталогам, и пытается их сам добавить в TOC. Этот вариант добавления в документации YDB не используется, любое включение всегда явное директивой include из другого TOC.

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

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