Global navigation

Global navigation defines how multiple documentation sets are organized and presented together in assembled documentation. It creates a unified navigation structure across all repositories.

Global navigation enables:

• Unified experience: Present documentation from multiple repositories as a cohesive whole.
• Flexible organization: Arrange documentation by product, feature, or audience rather than by repository.
• Independent evolution: Reorganize global structure without changing documentation sets.
• Cross-repository grouping: Combine related content from different repositories.

Global navigation is defined in the navigation.yml file, which is part of the site configuration. It follows a very similar toc configuration structure to documentation set navigation.

Global navigation has specific restrictions:

• It may only link to toc.yml or docset.yml files: You cannot reference individual markdown files.
• Uses crosslink syntax: References to other repositories use the repository:// syntax.
• Requires all TOC sections: Dangling TOC sections are not allowed.

toc:
  - toc: get-started
  - toc: elasticsearch-net://
  - toc: extend
    children:
      - toc: kibana://extend
        path_prefix: extend/kibana
      - toc: logstash://extend
        path_prefix: extend/logstash
      - toc: beats://extend
		

The TOC uses a similar cross-link syntax to links:

- toc: elasticsearch-net://
- toc: kibana://extend
		

1. References entire repository
2. References 'extend' TOC section from kibana

The ./docset.yml or /toc.yml suffix is implied - the assembler will find the correct file for you:

The narrative repository elastic/docs-content is 'special', so omitting scheme:// implies docs-content://:

- toc: get-started                 # Implies docs-content://get-started
- toc: elasticsearch://setup
		

1. Explicitly from elasticsearch repository

You must explicitly provide a URL path prefix when including a toc.

- toc: extend
  children:
    - toc: kibana://extend
      path_prefix: extend/kibana
    - toc: logstash://extend
      path_prefix: extend/logstash
    - toc: beats://extend
      path_prefix: extend/beats
		

1. Override default path

This allows you to:

• Group content from different repositories under a common path.
• Avoid URL conflicts when combining repositories.
• Create product-specific URL structures.

These toc sections can be reorganized independently of their position in their origin documentation set navigation. This allows sections from different repositories to be grouped together in the global navigation.

You can create a unified section that combines content from multiple repositories:

toc:
  - toc: monitoring
    children:
      - toc: elasticsearch://monitoring
        path_prefix: monitoring/elasticsearch
      - toc: kibana://monitoring
        path_prefix: monitoring/kibana
      - toc: beats://monitoring
        path_prefix: monitoring/beats
		

Even though each repository defines its own monitoring section, the global navigation presents them as a cohesive monitoring guide.

All toc sections must be linked in navigation.yml.

Dangling toc sections are not allowed and the assembler build will report an error if it finds any.

This ensures:

• No content is accidentally excluded from the site.
• Navigation references are always valid.
• Documentation coverage is complete.
• Every TOC section defined in a docset.yml appears somewhere in the global navigation.

If a repository defines:

# my-repo/docs/docset.yml
toc:
  - file: index.md
  - toc: getting-started
  - toc: advanced
		

Then navigation.yml must reference both getting-started and advanced:

# navigation.yml
toc:
  - toc: my-repo://getting-started
  - toc: my-repo://advanced
		

If either is missing, the build will fail with an error about dangling TOC sections.

When building assembled documentation, docs-builder validates:

• All referenced TOC sections exist.
• No TOC sections are dangling (unreferenced).
• Path prefixes don't conflict.
• Crosslink references resolve correctly.

Validation errors will cause the assembler build to fail.

You can customize how sections appear in global navigation:

Create nested navigation structures:

toc:
  - toc: getting-started
    children:
      - toc: elasticsearch://quickstart
      - toc: kibana://quickstart
  - toc: reference
    children:
      - toc: elasticsearch://apis
      - toc: elasticsearch://settings
		

During an assembler build:

1. docs-builder reads navigation.yml
2. It resolves all TOC section references across repositories
3. It validates that all sections are accounted for (no dangling sections)
4. It builds each documentation set with knowledge of its global path prefix
5. It generates the final site with unified navigation

• Documentation Set Navigation - How individual repositories organize their content.
• Assembled Documentation - The build process that uses global navigation.
• Site Configuration - Complete site configuration reference.
• Navigation Configuration - Detailed navigation.yml reference.
• Cross-link syntax - Understanding the <repository>://<path> syntax.