Loading

docset.yml file format

The docset.yml file (or _docset.yml) configures a content set's structure and metadata. It defines navigation, cross-links, substitutions, and other content set-level settings. The file is typically located at the root of the documentation folder (for example, docs/docset.yml or docs/_docset.yml).

For navigation structure and TOC syntax, see Navigation. For attributes and substitutions, see Attributes.

Field Required Default Description
project Optional — The name of the project.
toc Required — Table of contents defining the navigation structure. A minimal docset needs at least one file or folder reference.
suppress Optional [] Diagnostic hint types to suppress (for example, DeepLinkingVirtualFile, FolderFileNameMismatch).
max_toc_depth Optional 2 Maximum depth of the table of contents.
dev_docs Optional false When true, marks this documentation set as development docs that are not linkable by the assembler.
cross_links Optional [] Repositories to link to (for example, docs-content, apm-server).
exclude Optional [] Glob patterns for files to exclude from the TOC.
extensions Optional [] Extension configuration.
subs Optional {} Substitution key-value pairs for consistent terminology across the docset.
display_name Optional — Deprecated. Use the index.md H1 heading instead.
description Optional — Deprecated. Use the index.md frontmatter description instead.
icon Optional — Icon identifier for the documentation set.
registry Optional — Link index registry (for example, Public).
features Optional {} Feature flags (for example, primary-nav, disable-github-edit-link).
api Optional {} OpenAPI specification paths keyed by name.
products Optional [] Product IDs that this documentation set documents. Used for versioning and other product-aware features. Resolved against products.yml.
codex Optional — Codex-specific metadata (for example, group for navigation grouping).

The project name. Used for identification and display.

project: 'APM Java agent reference'

Defines the table of contents. Required for a valid docset. See Navigation for full TOC syntax and structure.

toc:
  - file: index.md
  - folder: getting-started
    children:
      - file: index.md
      - file: install.md

Suppresses specific diagnostic hints. Valid values include DeepLinkingVirtualFile, FolderFileNameMismatch, and AutolinkElasticCoDocs.

suppress:
  - DeepLinkingVirtualFile
  - FolderFileNameMismatch

Repositories you want to link to. Enables cross-repository links without absolute URLs. See Navigation for usage details.

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

Glob patterns for files to exclude from the TOC.

exclude:
  - '_*.md'

Substitution key-value pairs. Values can be referenced in Markdown as {{key}}. See Attributes for details.

subs:
  ea: "Elastic Agent"
  es: "Elasticsearch"

Feature flags that control docset behavior.

Sub-field Description
primary-nav Controls primary navigation display.
disable-github-edit-link Hides the GitHub edit link. 
features:
  primary-nav: false
  disable-github-edit-link: false

OpenAPI specification file paths, keyed by API name. Paths are relative to the documentation source directory.

api:
  elasticsearch: elasticsearch-openapi.json
  kibana: kibana-openapi.json

Product IDs that this documentation set documents. Each ID must exist in the global products.yml configuration. When omitted or empty, the docset has no product association.

products:
  - id: kibana

For a docset that documents multiple products:

products:
  - id: elasticsearch
  - id: kibana

Codex-specific metadata. The group field controls navigation grouping in codex environments.

codex:
  group: observability