Navigation

Two types of nav files are supported: docset.yml and toc.yml.

Example:

project: 'PROJECT_NAME'

external_hosts:
  - EXTERNAL_LINKS_HERE

exclude:
  - 'EXCLUDED_FILES'

toc:
  - file: index.md
  - toc: elastic-basics
  - folder: top-level-bucket-a
    children:
      - file: index.md
      - file: file-a.md
      - file: file-b.md
  - folder: top-level-bucket-b
    children:
      - file: index.md
      - folder: second-level-bucket-c
        children:
          - file: index.md

The name of the project.

Example:

project: 'APM Java agent reference'

All links to external hosts must be declared in this section of docset.yml.

Example:

external_hosts:
  - google.com
  - github.com

Files to exclude from the TOC. Supports glob patterns.

The following example excludes all markdown files beginning with _:

exclude:
  - '_*.md'

Defines the table of contents (navigation) for the content set. A minimal toc is:

toc:
  - file: index.md

The TOC in principle follows the directory structure on disk.

...
- folder: subsection

If a folder does not explicitly define children all markdown files within that folder are included automatically

If a folder does define children all markdown files within that folder have to be included. docs-builder will error if it detects dangling documentation files.

...
- folder: subsection
  children:
    - file: index.md
    - file: page-one.md
    - file: page-two.md

A file element may include children to create a virtual grouping that
does not match the directory structure.

...
- file: subsection/index.md
  children:
    - file: subsection/page-one.md
    - file: subsection/page-two.md

A file may only select siblings and more deeply nested files as its children. It may not select files outside its own subtree on disk.

A hidden file can be declared in the TOC.

- hidden: developer-pages.md

It may not have any children and won't show up in the navigation.

It may be linked to locally however

The toc key can include nested toc.yml files.

The following example includes two sub-toc.yml files located in directories named elastic-basics and solutions:

toc:
  - file: index.md
  - toc: elastic-basics
  - toc: solutions

Example:

subs:
  attr-name:   "attr value"
  ea:   "Elastic Agent"
  es:   "Elasticsearch"

See Attributes to learn more.

As a rule, each docset.yml file can only be included once in the assembler. This prevents us from accidentally duplicating pages in the docs. However, there are times when you want to split content sets and include them partially in different areas of the TOC. That's what toc.yml files are for. These files split one documentation set into multiple “sub-TOCs,” each mapped to a different navigation node.

A toc.yml file may only declare a nested TOC, other options are ignored.

A toc.yml may not link to further nested toc.yml files. Doing so will result in an error