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: elasticsearch-openapi.json
  kibana:
    - file: kibana-intro.md
    - spec: kibana-openapi.json
		

See API Explorer for full details.

Defines named call-to-action templates for the right-hand sidebar. 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.