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.

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.

See CTA.

Suppresses specific diagnostic hints:

suppress:
  - DeepLinkingVirtualFile
  - FolderFileNameMismatch
  - AutolinkElasticCoDocs
		

Suppresses hints about files with children that use deep-linking (paths containing /). Prefer folder: structures instead.

Suppresses hints about file names not matching folder names. Prefer matching names or index.md.

Suppresses hints about bare URLs pointing to elastic.co/docs. Prefer cross-links or relative links.