Creating customized documentation for YDB

The contents of thecore subdirectory are linked to various documentation build environments as a library for creating customized documentation.

Theoverlay subdirectory is designed for customizing content and is technical for an OpenSource build, since the OpenSource build does not contain core customizations.

Proxy articles

A file with an article incore never contains content directly, it only contains one or more instructions of include blocks of this content stored in the_includes subdirectory. As a result, replacing this file inoverlay does not lead to the need to copy the content, but lets you make the following types of its adaptation:

• Add additional content to the beginning or end of an article.
• Insert additional content between include directives.
• Remove some of the content of the original article from the build by removing the corresponding include directive.

Instructions for placing articles in core and overlay are given in theContent creation guide - Articles.

TOC (Table of Contents)

The TOC in the YDB documentation is built from a set of files placed in directories with articles that are hierarchically included in each other by the include directive. As a result, each of these files can be redefined separately in the adapted documentation.

As with articles, a proxy approach is used for TOC files as follows:

1. A file with menu items for core is namedtoc_i.yaml. It is never redefined inoverlay.
2. Next to thetoc_i.yaml file in core, there is a file namedtoc_p.yaml. It contains a link totoc_i.yaml and is designed to be redefined inoverlay.
3. Other sections are included in the TOC via a link to thetoc_p.yaml file.
4. If there is no need to adjust the contents of the TOC in a certain directory, no toc* files are created inoverlay. This results in using toc_p —> toc_i from core in the build.
5. If the contents of the TOC need to be adjusted in a certain directory, a file namedtoc_p.yaml is created inoverlay with the- include: { mode: link, path: toc_i.yaml } from core added to its content and additional items for the adapted build added above or below.

It is good practice not to include the “Overview” in toc_i.yaml but rather include it directly in toc_p.yaml instead. This article must be the first in each submenu and always has the same article name (index.md). Including a separate item in toc_p lets you add new articles to the adapted documentation before the articles from core, but keeping the “Overview” in the first place:

toc_p.yaml in some corporate overlay:

items:
- name: Overview
  href: index.md
- name: Employee roles
  href: corp_roles.md
- include: { mode: link, path: toc_i.yaml }
- name: Corporate authorization
  href: corp_auth.md

As with articles, core may have several toc_i*.yaml files included in toc_p with separate includes.

There are also a couple of toc_i and toc_p files in the root directory, representing the top level of the table of contents.

Since the inclusion of files is implemented through references to them from the parent toc, a file name may actually be technically anything and the above is only a naming convention. However, there is one restriction:

Warning

A TOC file name may not betoc.yaml, since the build tool searches for files with this name across all subdirectories and tries to add them to the TOC on its own. This include option is not used in the YDB documentation, any inclusion is always explicit by the include directive from another TOC.

The only exception is the initialtoc.yaml that is placed in the documentation build root and always contains the command to copy the core content and proceed to TOC handling in core:include: { mode: merge, path: core/toc_m.yaml }.

Instructions for making a TOC in core and overlay are given in theContent creation guide - TOC.