docset.yml reference

The docset.yml file is the configuration file for a documentation set. At minimum, a documentation set needs a docset.yml and an index.md in the same folder.

For an overview of navigation concepts and common patterns, see Navigation.

Unknown keys in docset.yml and in nested toc.yml files are build errors, so a typo is never silently ignored. Each error points at the key, shows where it sits in the file, and suggests the closest valid key:

Error: Unknown key 'fiel' in $.toc[1]. Did you mean 'file'?
 5 │   - fiel: other.md
   ·     ────
		

If no valid key is close, the error lists the valid keys for that position. The same applies to frontmatter, redirects.yml, {settings} files, and the other YAML the build reads.

The name of the project.

project: 'APM Java agent reference'
		

Defines the table of contents (navigation) for the content set:

toc:
  - file: index.md
		

Adds a page to the navigation:

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

A file can include children to create a virtual grouping. Children must be siblings (same directory) or deeper:

- file: getting-started.md
  children:
    - file: installation.md
    - file: configuration.md
		

Groups pages under a directory. Without children, all markdown files in the folder are included automatically:

- folder: api
		

With explicit children, all markdown files in the folder must be listed:

- folder: api
  children:
    - file: index.md
    - file: authentication.md
		

Controls sort order when auto-discovering files (no explicit children):

- folder: api-versions
  sort: desc
		

Valid values: asc, ascending, desc, descending. Default is ascending. index.md is always first regardless of sort order.

Excludes specific files from auto-discovery:

- folder: subsection
  exclude:
    - draft.md
    - internal-notes.md
		

Includes a page in the build but hides it from the navigation:

- hidden: developer-notes.md
		

References a separate toc.yml file for modularity:

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

Declares repositories whose link indexes should be fetched for cross-link validation:

cross_links:
  - apm-server
  - cloud
  - docs-content
		

Use cross-link syntax in Markdown: [text](docs-content://directory/file.md) or with anchors: [text](docs-content://directory/file.md#section-id).

Cross-links can also appear in navigation:

toc:
  - file: index.md
  - title: External Documentation
    crosslink: docs-content://directory/file.md
		

Files to exclude from the build. Supports glob patterns:

exclude:
  - '_*.md'
		

Defines substitution variables as key-value pairs. Use {{name}} in Markdown to reference them:

subs:
  es: "Elasticsearch"
  kib: "Kibana"
  agent: "Elastic Agent"
		

See Substitutions for the full syntax including mutations.

Configures API Explorer sections from OpenAPI specifications. Only valid in docset.yml, not toc.yml:

api:
  elasticsearch:
    - spec: elasticsearch-openapi.json
      product: elasticsearch
  kibana:
    - spec: kibana-openapi.json
      product: kibana
      children:
        - file: kibana-api-overview.md
		

See API Explorer for full details.

Defines named call-to-action templates for the right-hand sidebar. See CTA.

Registers a named CTA template as the default for every page listed in this navigation file. Available on both docset.yml and nested toc.yml files. The template must be declared under the cta map in docset.yml.

default_cta can also be set on an individual file: or folder: entry inside toc, where it applies to that entry and every page beneath it:

toc:
  - file: observability.md
    default_cta: observability
    children:
      - folder: observability
		

See CTA.

Suppresses specific diagnostic hints. Available in docset.yml and in nested toc.yml files:

suppress:
  - DeepLinkingVirtualFile
  - FolderFileNameMismatch
  - AutolinkElasticCoDocs
		

Where you put suppress decides which navigation entries it covers:

• In docset.yml, the list applies to the entries declared in docset.yml itself.
• In a nested toc.yml, the list applies only to the entries in that toc.yml. It doesn't carry over to docset.yml or to other toc.yml files, and a toc.yml doesn't inherit the list from docset.yml.

AutolinkElasticCoDocs is raised while Markdown is parsed, so it's only read from docset.yml and applies to every page in the docset.

Suppresses the hint for a file: with children whose path contains /, for example file: other/x.md with children in other/. Prefer restructuring to a folder: instead. Only suppress the hint when the structure has to stay as it is:

- folder: other
  file: index.md
		

When you switch to folder: with file: index.md and no children, the folder picks up every Markdown file automatically. If you give the folder: explicit children, list every Markdown file in the folder, or the build fails with "is not listed in the table of contents" for each file you leave out. Moving the page to folder: can change its URL, so check the URLs before and after.

Suppresses hints about file names not matching folder names in a folder: with a file:. Prefer matching names or index.md.

Suppresses hints about bare URLs pointing to elastic.co/docs. Prefer cross-links or relative links. Only valid in docset.yml.