Pages and links

Every documentation set needs a docset.yml that declares which pages exist and how they're organized in the navigation.

Pages are listed under the toc: key in your docset.yml:

toc:
  - file: index.md
  - file: getting-started.md
  - file: configuration.md
		

Each - file: entry adds a page to the sidebar navigation in the order listed.

Group related pages under a folder:

toc:
  - file: index.md
  - folder: guides
    children:
      - file: index.md
      - file: quickstart.md
      - file: advanced.md
		

For larger documentation sets, you can split navigation into separate toc.yml files:

# docset.yml
toc:
  - file: index.md
  - toc: guides
		

# guides/toc.yml
toc:
  - file: index.md
  - file: quickstart.md
		

See navigation configuration for the complete reference.

Use relative Markdown links to reference other pages:

See the [configuration guide](./configuration.md) for details.

Refer to the [advanced section](../guides/advanced.md#specific-heading).
		

Links are validated at build time — broken links produce errors.

To link to pages in other repositories, use cross-link syntax:

[Getting started with Elasticsearch](elasticsearch://reference/getting-started.md)
		

The format is <repository>://<path-to-file>. The repository name matches the GitHub repository name without the org prefix.

Before using cross-links, declare the target repositories in your docset.yml:

cross_links:
  - elasticsearch
  - kibana
  - docs-content
		

This tells docs-builder to fetch the link index for each listed repository so it can validate your cross-links at build time — even during local development.

• Serve and preview — preview your docs locally with hot reload
• Content set configuration — full docset.yml reference
• Links syntax — complete link syntax including anchors and titles