navigation.yml

The navigation.yml file acts as a global navigation index. Each entry points to a toc.yml file, which contains the navigation tree for that section. This design allows each section/project/team to manage its own navigation independently of other content sets.

Example:

toc:
  - toc: get-started
  - toc: extend
    children:
      - toc: kibana://extend
        path_prefix: extend/kibana
  1. No toc.yml indicates a docs-content directory
  2. A toc.yml file in the Kibana repo at docs/extend
  3. The URL path for built content will be elastic.co/docs/extend/kibana/FILE_PATH+NAME

The location of the table of contents file.

repo_name://path-relative-to-toc.yml

A section: entry with floating: api puts the API pages of the site in the navigation tree:

toc:
  - section: APIs
    floating: api

When the build renders the API Explorer (the assembler-api-explorer feature flag), every API that a content repository declares in the api: block of its docset.yml becomes a child of the section. The docset needs no entry for it in its own table of contents. The section links to /api/, and each API is an island with its own sidebar. Only the current version of each API is visible, so older versions stay out of the sitemap and the llms.txt listing. The sitemap and the llms.txt listing read the section like any other part of the tree. The section is empty and adds nothing to a build that does not render the API Explorer.

A section can also have an external: link, as the APIs tab of the navigation preview does. The tab keeps its link, and the tree gets the APIs when the build has any:

- section: APIs
  external: /api/
  floating: api

The path_prefix configuration key specifies the URL path segment that should be prefixed to all documentation URLs.

listing all documentation sources and the corresponding toc.yml file that defines their navigation.

table of roots and specifying the location of each documentation section’s table of contents (toc.yml) file. Every entry in navigation.yml must reference a toc.yml file, which actually defines the navigation structure for that documentation section.

defines the structure and organization of the navigation menu for the Elastic documentation site.

The file is composed of nested YAML objects, where each object represents a navigation node. Navigation nodes can be categories, sections, or links to documentation pages.

Once the repository is added, its navigation still needs to be injected into to global site navigation.