From e2dbc444bd5e19c02968324107c11d80b1692765 Mon Sep 17 00:00:00 2001
From: lcawl <lcawley@elastic.co>
Date: Fri, 3 Jul 2026 14:18:10 -0700
Subject: [PATCH] Add missing reference details for docset.yml and toc.yml

---
 docs/_docset.yml                              |   2 +
 .../documentation-set-navigation.md           |  88 +---
 docs/building-blocks/documentation-set.md     |   2 +-
 docs/configure/content-set/api-explorer.md    |   2 +
 docs/configure/content-set/attributes.md      |   2 +
 docs/configure/content-set/cta.md             |   2 +
 .../configure/content-set/docset-reference.md | 329 ++++++++++++
 docs/configure/content-set/extensions.md      |   6 +-
 docs/configure/content-set/index.md           |  21 +-
 docs/configure/content-set/navigation.md      | 469 +-----------------
 docs/configure/content-set/toc-reference.md   | 189 +++++++
 docs/contribute/add-repo.md                   |   2 +-
 docs/migration/guide/automated.md             |   2 +-
 13 files changed, 577 insertions(+), 539 deletions(-)
 create mode 100644 docs/configure/content-set/docset-reference.md
 create mode 100644 docs/configure/content-set/toc-reference.md

diff --git a/docs/_docset.yml b/docs/_docset.yml
index c46346047b..febb5922d5 100644
--- a/docs/_docset.yml
+++ b/docs/_docset.yml
@@ -122,6 +122,8 @@ toc:
       - folder: content-set
         children:
           - file: index.md
+          - file: docset-reference.md
+          - file: toc-reference.md
           - file: file-structure.md
           - file: attributes.md
           - file: navigation.md
diff --git a/docs/building-blocks/documentation-set-navigation.md b/docs/building-blocks/documentation-set-navigation.md
index 215dfae91d..58b522fb68 100644
--- a/docs/building-blocks/documentation-set-navigation.md
+++ b/docs/building-blocks/documentation-set-navigation.md
@@ -353,11 +353,9 @@ toc:
 
 ## Suppressing diagnostic hints
 
-As you build navigation, the docs-builder may emit hints suggesting improvements to your structure. These hints help maintain best practices but can be suppressed when you have valid reasons to deviate.
+As you build navigation, `docs-builder` may emit hints suggesting improvements to your structure. Suppress them when you have a valid reason to deviate — for example during a legacy migration or when external links depend on an established URL pattern.
 
-### Available suppressions
-
-Add a `suppress` section to either `docset.yml` or `toc.yml`:
+Add a `suppress` section to `docset.yml` or `toc.yml`:
 
 ```yaml
 suppress:
@@ -366,89 +364,20 @@ suppress:
 
 toc:
   - file: index.md
-  # ... rest of your navigation
-```
-
-### DeepLinkingVirtualFile
-
-**What it detects**: Files with children that use paths containing `/`:
-
-```yaml
-toc:
-  - file: guides/advanced/performance.md
-    children:
-      - file: guides/advanced/caching.md
-      - file: guides/advanced/optimization.md
-```
-
-**Why it hints**: Virtual files (files with children) work best for grouping sibling files together. Using deep paths suggests you might benefit from proper folder structures.
-
-**When to suppress**: Rarely. This usually indicates a structural issue. Consider refactoring to use folders or nested toc files instead.
-
-**Better alternative**:
-```yaml
-toc:
-  - folder: guides
-    children:
-      - folder: advanced
-        children:
-          - file: index.md
-          - file: performance.md
-            children:
-              - file: caching.md
-              - file: optimization.md
 ```
 
-### FolderFileNameMismatch
-
-**What it detects**: Folder and file combinations where names don't match:
-
-```yaml
-toc:
-  - folder: getting-started
-    file: overview.md      # Doesn't match folder name
-```
-
-**Why it hints**: Matching names create predictable, consistent navigation. When a folder is named "getting-started," readers expect the main file to be either `getting-started.md` or `index.md`.
-
-**When to suppress**: When you have legacy documentation with established naming conventions, or when the file name is intentionally different for clarity.
-
-**Better alternatives**:
-```yaml
-# Option 1: Match the names
-- folder: getting-started
-  file: getting-started.md
-
-# Option 2: Use index.md (conventional and always appropriate)
-- folder: getting-started
-  file: index.md
-
-# Option 3: Just use folder with children
-- folder: getting-started
-  children:
-    - file: index.md
-    - file: prerequisites.md
-```
-
-### When to use suppressions
-
-Suppressions are escape hatches, not defaults. Use them when:
+Valid values and what each hint detects are documented in [`docset.yml` reference](../configure/content-set/docset-reference.md#suppress) and [TOC reference](../configure/content-set/toc-reference.md#suppress).
 
-* **Migrating legacy content**: Existing documentation has established patterns that can't be changed immediately
-* **Valid architectural reasons**: Your specific use case genuinely benefits from the flagged pattern
-* **Temporary transitions**: You're in the middle of restructuring and need to suppress hints during the migration
+**Example of justified suppression:**
 
-**Example of justified suppression**:
 ```yaml
-# This section uses an established URL structure we can't change
-# without breaking external links. Suppressing the hint until we
-# can implement proper redirects.
+# Established URL structure we can't change without breaking external links.
 suppress:
   - FolderFileNameMismatch
 
 toc:
   - folder: install
-    file: setup.md  # External links point to /install/setup
+    file: setup.md
     children:
       - file: prerequisites.md
 ```
@@ -574,5 +503,6 @@ Choose names that:
 ## Related concepts
 
 * [Global Navigation](global-navigation.md) - How documentation sets are organized in assembled documentation.
-* [Content Set Configuration](../configure/content-set/index.md) - Complete `docset.yml` reference.
-* [Navigation Configuration](../configure/content-set/navigation.md) - Detailed navigation options.
+* [`docset.yml` reference](../configure/content-set/docset-reference.md) - All top-level configuration keys.
+* [TOC reference](../configure/content-set/toc-reference.md) - Syntax for `toc` array entries.
+* [Navigation layout](../configure/content-set/navigation.md) - Entry point for structuring navigation.
diff --git a/docs/building-blocks/documentation-set.md b/docs/building-blocks/documentation-set.md
index 4446fafe40..b6399acf99 100644
--- a/docs/building-blocks/documentation-set.md
+++ b/docs/building-blocks/documentation-set.md
@@ -41,7 +41,7 @@ my-repo/
 
 ## Configuration
 
-The `docset.yml` file controls how the documentation set is structured and built. See [Content Set Configuration](../configure/content-set/index.md) for complete configuration details.
+The `docset.yml` file controls how the documentation set is structured and built. See [`docset.yml` reference](../configure/content-set/docset-reference.md) for all configuration keys.
 
 ## Related concepts
 
diff --git a/docs/configure/content-set/api-explorer.md b/docs/configure/content-set/api-explorer.md
index 836efaff93..82d05937a1 100644
--- a/docs/configure/content-set/api-explorer.md
+++ b/docs/configure/content-set/api-explorer.md
@@ -4,6 +4,8 @@ navigation_title: API Explorer
 
 # API Explorer
 
+For the full list of `docset.yml` keys, see [`docset.yml` reference](docset-reference.md).
+
 The API Explorer renders OpenAPI specifications as interactive API documentation. When you configure it in your content set, `docs-builder` automatically generates pages for each API operation, request and response schemas, shared type definitions, and inline examples.
 
 :::{warning}
diff --git a/docs/configure/content-set/attributes.md b/docs/configure/content-set/attributes.md
index cf4344f93f..4f53c24362 100644
--- a/docs/configure/content-set/attributes.md
+++ b/docs/configure/content-set/attributes.md
@@ -1,5 +1,7 @@
 # Attributes
 
+For the full list of `docset.yml` keys, see [`docset.yml` reference](docset-reference.md).
+
 To promote consistency across documentation, AsciiDoc uses shared attributes for common terms, URLs, and versions.
 
 In the AsciiDoctor-based system, shared attributes are defined at the site-level and live in the [`shared/` directory](https://github.com/elastic/docs/blob/master/shared) in the elastic/docs repo. The most used files in this directory are:
diff --git a/docs/configure/content-set/cta.md b/docs/configure/content-set/cta.md
index 37bff5b229..02b6a16fdc 100644
--- a/docs/configure/content-set/cta.md
+++ b/docs/configure/content-set/cta.md
@@ -6,6 +6,8 @@ cta:
 
 # CTA
 
+For the full list of `docset.yml` keys, see [`docset.yml` reference](docset-reference.md).
+
 The CTA (call-to-action) feature renders a card in the right-hand sidebar of a page, with a button and a short list of benefits. By default, every page shows the built-in `trial` card. Docsets can define their own named CTA templates and have individual pages opt into them.
 
 ## Define CTA templates
diff --git a/docs/configure/content-set/docset-reference.md b/docs/configure/content-set/docset-reference.md
new file mode 100644
index 0000000000..c50c70691c
--- /dev/null
+++ b/docs/configure/content-set/docset-reference.md
@@ -0,0 +1,329 @@
+---
+navigation_title: docset.yml reference
+---
+
+# `docset.yml` reference
+
+Every content set has a `docset.yml` file at its root. Larger content sets can also define `toc.yml` files in subfolders. Both files share a subset of keys; `docset.yml` alone supports the full set of content-set configuration options.
+
+For syntax of entries inside the `toc` array, see [TOC reference](toc-reference.md). For layout patterns and trade-offs, see [Navigation layout](navigation.md).
+
+## Key applicability
+
+| Key | `docset.yml` | `toc.yml` |
+|-----|:------------:|:---------:|
+| `project` | ✓ | ✓ |
+| `toc` | ✓ | ✓ |
+| `suppress` | ✓ | ✓ |
+| `subs` | ✓ | ✓ |
+| `max_toc_depth` | ✓ | |
+| `dev_docs` | ✓ | |
+| `cross_links` | ✓ | |
+| `release_notes` | ✓ | |
+| `exclude` | ✓ | |
+| `extensions` | ✓ | |
+| `api` | ✓ | |
+| `features` | ✓ | |
+| `products` | ✓ | |
+| `codex` | ✓ | |
+| `branding` | ✓ | |
+| `storybook` | ✓ | |
+| `cta` | ✓ | |
+| `registry` | ✓ | |
+| `icon` | ✓ | |
+| `display_name` | ✓ (deprecated) | |
+| `description` | ✓ (deprecated) | |
+
+## Keys in both `docset.yml` and `toc.yml`
+
+### `project`
+
+**Type:** string
+
+The name of the project or documentation set.
+
+```yaml
+project: 'APM Java agent reference'
+```
+
+### `toc`
+
+**Type:** list of navigation entries
+
+Defines the table of contents for the content set. See [TOC reference](toc-reference.md) for entry types and sub-keys.
+
+```yaml
+toc:
+  - file: index.md
+  - folder: guides
+    children:
+      - file: index.md
+```
+
+### `suppress`
+
+**Type:** list of hint type names
+
+Suppresses diagnostic hints for this navigation file. Valid values:
+
+| Value | Description |
+|-------|-------------|
+| `DeepLinkingVirtualFile` | Files with `children` that use a path containing `/` |
+| `FolderFileNameMismatch` | `folder` + `file` combinations where the file name does not match the folder name |
+| `AutolinkElasticCoDocs` | Bare `https://` URLs pointing at `elastic.co/docs` |
+
+```yaml
+suppress:
+  - DeepLinkingVirtualFile
+  - FolderFileNameMismatch
+```
+
+### `subs`
+
+**Type:** map of string → string
+
+Content-set-level [substitutions](../../syntax/substitutions.md) (attributes). Merged with page-level `sub` frontmatter.
+
+```yaml
+subs:
+  ea: Elastic Agent
+  es: Elasticsearch
+```
+
+See [Attributes](attributes.md).
+
+## Keys in `docset.yml` only
+
+### `max_toc_depth`
+
+**Type:** integer · **Default:** `2`
+
+Maximum nesting depth for `toc:` entries that reference nested `toc.yml` files. By default, only `docset.yml` may reference `toc.yml` files; increasing this value allows nested `toc.yml` files to reference other `toc.yml` files. Consult the docs team before raising this limit.
+
+```yaml
+max_toc_depth: 2
+```
+
+### `dev_docs`
+
+**Type:** boolean · **Default:** `false`
+
+Marks the documentation set as developer documentation. Relaxes some restrictions around TOC building and file placement. Developer docsets are not linkable by the assembler.
+
+```yaml
+dev_docs: true
+```
+
+### `cross_links`
+
+**Type:** list of repository names (or `registry://repository` URIs)
+
+Declares repositories whose [link indexes](../../building-blocks/link-index.md) this content set may link to. Required for `repo://` cross-link syntax in Markdown and navigation.
+
+```yaml
+cross_links:
+  - docs-content
+  - elasticsearch
+```
+
+Entries may include an optional registry prefix (`public://` or `internal://`). The docset-level `registry` key sets the default prefix for entries without one.
+
+See [Outbound cross-links](../../building-blocks/outbound-cross-links.md) and [Links](../../syntax/links.md).
+
+### `release_notes`
+
+**Type:** list of product references
+
+Declares products whose changelog bundles are sourced from the public CDN. Required for the `{changelog}` directive's `:cdn:` mode and for `changelog bundle` to source entries from the CDN.
+
+```yaml
+release_notes:
+  - product: elasticsearch
+  - product: edot-java
+```
+
+Each `product` must be a product id from `products.yml` that participates in the release-notes system.
+
+See [Declaring CDN-backed products](../../syntax/changelog.md#declaring-cdn-backed-products) and [Changelog bundle registry](../../development/changelog-bundle-registry.md).
+
+### `exclude`
+
+**Type:** list of glob patterns
+
+Excludes files from the content set. Patterns starting with `!` re-include files that would otherwise be excluded.
+
+```yaml
+exclude:
+  - '_*.md'
+  - '!_search.md'
+```
+
+### `extensions`
+
+**Type:** list of extension names
+
+Opts into content-set extensions that are disabled by default.
+
+```yaml
+extensions:
+  - detection-rules
+```
+
+See [Extensions](extensions.md).
+
+### `api`
+
+**Type:** map of product name → OpenAPI spec path or sequence
+
+Configures [API Explorer](api-explorer.md) sections. Paths are relative to the folder containing `docset.yml`. Not valid in `toc.yml`.
+
+```yaml
+api:
+  elasticsearch: elasticsearch-openapi.json
+  kibana:
+    - file: kibana-intro.md
+    - spec: kibana-openapi.json
+```
+
+### `features`
+
+**Type:** map of feature flags
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `primary-nav` | boolean | Enables the primary navigation dropdown (requires Elastic global navigation; incompatible with `branding`) |
+| `disable-github-edit-link` | boolean | Hides the **Edit this page on GitHub** link |
+
+```yaml
+features:
+  primary-nav: false
+  disable-github-edit-link: true
+```
+
+### `products`
+
+**Type:** list of product references
+
+Default products for the documentation set. Merged with page-level `products` frontmatter.
+
+```yaml
+products:
+  - id: apm-agent
+  - id: edot-sdk
+```
+
+See [Products frontmatter](../../syntax/frontmatter.md#products).
+
+### `codex`
+
+**Type:** map
+
+Codex-specific metadata for internal documentation environments.
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `group` | string | Navigation group id for codex landing pages |
+
+```yaml
+codex:
+  group: observability
+```
+
+### `branding`
+
+**Type:** map
+
+White-label branding overrides for isolated builds. When present, Elastic-specific chrome is suppressed. Image paths are relative to the folder containing `docset.yml`.
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `icon` | string | Site icon image path |
+| `header-bg` | string | CSS colour for the header background (default: `#000000`) |
+| `og-image` | string | Open Graph image path |
+| `favicon` | string | Browser favicon path (auto-discovered from `favicon.ico`, `favicon.png`, or `favicon.svg` when omitted) |
+| `apple-touch-icon` | string | Apple touch icon path (auto-discovered from `apple-touch-icon.png` when omitted) |
+
+```yaml
+branding:
+  icon: images/logo.svg
+  header-bg: '#1a1a2e'
+  favicon: favicon.ico
+```
+
+Cannot be used together with `features.primary-nav: true`.
+
+### `storybook`
+
+**Type:** map
+
+Configures the Storybook registry for the `{storybook}` directive.
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `registry` | string | URL to a Kibana `docs_registry.json` file. Supports `${KIBANA_STORYBOOK_REGISTRY:-default}` interpolation. |
+
+```yaml
+storybook:
+  registry: https://ci-artifacts.kibana.dev/storybooks/main/storybook-docs/docs_registry.json
+```
+
+See [Storybook](../../syntax/storybook.md).
+
+### `cta`
+
+**Type:** map of template name → definition
+
+Named right-gutter call-to-action templates. Pages select a template via `cta.id` frontmatter.
+
+```yaml
+cta:
+  beta:
+    button:
+      label: Join the private beta
+      url: https://example.com/beta
+    benefits:
+      - Early access to new features
+```
+
+See [CTA](cta.md).
+
+### `registry`
+
+**Type:** string · **Default:** `public`
+
+Default link-index registry for `cross_links` entries that omit a registry prefix.
+
+| Value | Description |
+|-------|-------------|
+| `public` | S3-based public link index (default) |
+| `internal` | Codex internal link index |
+
+```yaml
+registry: public
+```
+
+Cross-link entries may override the default: `internal://my-docset`.
+
+### `icon`
+
+**Type:** string
+
+Optional icon identifier for codex documentation-set cards. Distinct from `branding.icon`, which applies to white-label site chrome.
+
+### `display_name` (deprecated)
+
+**Type:** string
+
+Deprecated. Use the `index.md` H1 heading instead. This field will be removed in a future version.
+
+### `description` (deprecated)
+
+**Type:** string
+
+Deprecated. Use page frontmatter `description` instead. This field will be removed in a future version.
+
+## Related topics
+
+* [TOC reference](toc-reference.md) — syntax for `toc` array entries
+* [Navigation layout](navigation.md) — patterns for organizing navigation
+* [File structure](file-structure.md) — how directories map to URLs
diff --git a/docs/configure/content-set/extensions.md b/docs/configure/content-set/extensions.md
index ae64a6e8ed..81132707b2 100644
--- a/docs/configure/content-set/extensions.md
+++ b/docs/configure/content-set/extensions.md
@@ -2,7 +2,9 @@
 navigation_title: Extensions
 ---
 
-# Content set extensions. 
+# Content set extensions.
+
+For the full list of `docset.yml` keys, see [`docset.yml` reference](docset-reference.md).
 
 The documentation engineering team will on occasion built extensions for specific use-cases.
 
@@ -21,7 +23,7 @@ extensions:
   - detection-rules
 ```
 
-This now allows you to use the special `detection_rules` instruction in the [Table of Contents](navigation.md)
+This now allows you to use the special `detection_rules` instruction in the [TOC reference](toc-reference.md#detection_rules)
 As a means to pick up `toml` files as `children`
 
 ```yaml
diff --git a/docs/configure/content-set/index.md b/docs/configure/content-set/index.md
index f8432d538c..4ab0459ab6 100644
--- a/docs/configure/content-set/index.md
+++ b/docs/configure/content-set/index.md
@@ -13,11 +13,20 @@ A content set in `docs-builder` is equivalent to an AsciiDoc book. At this level
 | **Content source files** --> A whole bunch of markup files as well as any other assets used in the docs (for example, images, videos, and diagrams).   | **Markup**: AsciiDoc files **Assets**: Images, videos, and diagrams                                                                                   | **Markup**: MD files **Assets**: Images, videos, and diagrams |
 | **Information architecture** --> A way to specify the order in which these text-based files should appear in the information architecture of the book. | `index.asciidoc` file (this can be spread across several AsciiDoc files, but generally starts with the index file specified in the `conf.yaml` file)) | `docset.yml` and/or `toc.yml` file(s)                         |
 
+## Reference
+
+* [`docset.yml` reference](./docset-reference.md) — all top-level configuration keys
+* [TOC reference](./toc-reference.md) — syntax for `toc` array entries
+* [Attributes](./attributes.md) — `subs` substitutions
+* [Extensions](./extensions.md) — optional content-set extensions
+* [API Explorer](./api-explorer.md) — `api` OpenAPI configuration
+* [CTA](./cta.md) — right-gutter call-to-action templates
+
+## Layout
+
+* [File structure](./file-structure.md) — how directories map to URLs
+* [Navigation layout](./navigation.md) — structuring the `toc` tree
+
 ## Learn more
 
-* [File structure](./file-structure.md).
-* [Navigation](./navigation.md).
-* [Attributes](./attributes.md).
-* [Extensions](./extensions.md).
-* [API Explorer](./api-explorer.md).
-* [CTA](./cta.md).
\ No newline at end of file
+* [Documentation set navigation](../../building-blocks/documentation-set-navigation.md) — patterns, trade-offs, and worked examples
diff --git a/docs/configure/content-set/navigation.md b/docs/configure/content-set/navigation.md
index 8d271cb1fc..745e88679e 100644
--- a/docs/configure/content-set/navigation.md
+++ b/docs/configure/content-set/navigation.md
@@ -1,466 +1,37 @@
-# Navigation
+---
+navigation_title: Navigation layout
+---
 
-Two types of nav files are supported: `docset.yml` and `toc.yml`.
+# Navigation layout
 
-## `docset.yml`
+Navigation structure is defined in the `toc` key of `docset.yml` (and optionally in nested `toc.yml` files). Two nav file types are supported:
 
-Example:
+* **`docset.yml`** — root configuration for the content set
+* **`toc.yml`** — optional per-folder navigation for large sections
 
-```yaml
-project: 'PROJECT_NAME'
-
-exclude:
-  - 'EXCLUDED_FILES'
-
-toc:
-  - file: index.md
-  - toc: elastic-basics
-  - folder: top-level-bucket-a
-    children:
-      - file: index.md
-      - file: file-a.md
-      - file: file-b.md
-  - folder: top-level-bucket-b
-    children:
-      - file: index.md
-      - folder: second-level-bucket-c
-        children:
-          - file: index.md
-```
-
-### `project`
-
-The name of the project.
-
-Example:
-
-```yaml
-project: 'APM Java agent reference'
-```
-
-### `cross_links`
+## Reference
 
-Defines repositories that contain documentation sets you want to link to. The purpose of this feature is to avoid using absolute links that require time-consuming crawling and checking.
+* [`docset.yml` reference](docset-reference.md) — all top-level configuration keys (`cross_links`, `api`, `release_notes`, and more)
+* [TOC reference](toc-reference.md) — syntax for `file`, `folder`, `hidden`, `toc`, `crosslink`, and other `toc` entry types
 
-Consider a docset repository called `bazinga`. The following example adds three docset repositories to its `docset.yml` file:
+## Layout patterns
 
-```yaml
-cross_links:
-  - apm-server
-  - cloud
-  - docs-content
-```
+For patterns, trade-offs, and worked examples — when to use a `folder` without `children`, virtual file groupings, nested `toc.yml` files, and mixed structures — see [Documentation set navigation](../../building-blocks/documentation-set-navigation.md).
 
-#### Adding cross-links in Markdown content
+That guide covers:
 
-To link to a document in the `docs-content` repository, you would write the link as follows:
-
-```markdown
-[Link to docs-content doc](docs-content://directory/another-directory/file.md)
-```
-
-You can also link to specific anchors within the document:
-
-```markdown
-[Link to specific section](docs-content://directory/file.md#section-id)
-```
+* TOC node types and file path rules
+* Dedicated `toc.yml` files for modular sections
+* Common patterns (single file, folder with explicit children, folder + file combination, nested toc references)
+* Suppressing diagnostic hints when you have a valid reason to deviate from defaults
 
-#### Adding cross-links in navigation
+## Minimum navigation
 
-Cross-links can also be included in navigation structures. When creating a `toc.yml` file or defining navigation in `docset.yml`, you can add cross-links as follows:
+At minimum, every content set needs an `index.md` referenced in `toc`:
 
 ```yaml
 toc:
   - file: index.md
-  - title: External Documentation
-    crosslink: docs-content://directory/file.md
-  - folder: local-section
-    children:
-      - file: index.md
-      - title: API Reference
-        crosslink: elasticsearch://api/index.html
 ```
 
-Cross-links in navigation will be automatically resolved during the build process, maintaining consistent linking between related documentation across repositories.
-
-### `exclude`
-
-Files to exclude from the TOC. Supports glob patterns.
-
-The following example excludes all markdown files beginning with `_`:
-
-```yaml
-exclude:
-  - '_*.md'
-```
-
-### `api`
-
-Configures API Explorer sections for your content set using OpenAPI specification files and optional intro/outro pages. Paths are relative to the folder containing `docset.yml`. Only valid in `docset.yml`, not in `toc.yml` files.
-
-#### Basic configuration
-
-```yaml
-api:
-  elasticsearch: elasticsearch-openapi.json
-  kibana: kibana-openapi.json
-```
-
-#### Advanced configuration with intro/outro pages
-
-```yaml
-api:
-  kibana:
-    - file: kibana-intro.md
-    - spec: kibana-openapi.json
-    - file: kibana-outro.md
-```
-
-Each product key becomes a sub-path of the generated API docs: `elasticsearch` → `/api/elasticsearch/`, `kibana` → `/api/kibana/`.
-
-The sequence format allows you to add custom Markdown content:
-- **Intro pages** (before the first `spec`) appear at the top of the API navigation
-- **Generated content** (operations, tags, types) appears in the middle  
-- **Outro pages** (after specs) appear at the bottom
-
-See [API Explorer](api-explorer.md) for full configuration details and examples.
-
-### `toc`
-
-Defines the table of contents (navigation) for the content set. A minimal toc is:
-
-```yaml
-toc:
-  - file: index.md
-```
-
-The TOC in principle follows the directory structure on disk.
-
-#### `folder:`
-
-```yaml
-  ...
-  - folder: subsection
-```
-
-If a folder does not explicitly define `children` all markdown files within that folder are included automatically
-
-If a folder does define `children` all markdown files within that folder have to be included. `docs-builder` will error if it detects dangling documentation files.
-
-```yaml
-  ...
-  - folder: subsection
-    children:
-      - file: index.md
-      - file: page-one.md
-      - file: page-two.md
-```
-
-##### `sort`
-
-When auto-discovering files (no explicit `children`), you can control the sort order with `sort`:
-
-```yaml
-  ...
-  - folder: api-versions
-    sort: desc
-```
-
-Valid values are `asc`, `ascending`, `desc`, and `descending`. The default is ascending (A-Z). When set to descending, files are listed Z-A, which is useful for version-numbered folders where the newest version should appear first. Sorting uses natural order, so version numbers sort correctly (`3_2_0` comes before `3_10_0`). `index.md` is always placed first regardless of sort order.
-
-The `sort` option has no effect when `children` are explicitly defined, since the order is determined by the `children` list.
-
-##### `exclude`
-
-When using auto-discovery (no explicit `children`), you can exclude specific files from being included:
-
-```yaml
-  ...
-  - folder: subsection
-    exclude:
-      - draft.md
-      - internal-notes.md
-```
-
-Excluded file names are matched case-insensitively. This is useful when a folder contains files that should not appear in the navigation, like drafts or internal documentation.
-
-The `exclude` option has no effect when `children` are explicitly defined, since all files must be listed manually.
-
-#### Virtual grouping
-
-A `file` element can include children to create a virtual grouping that
-does not match the directory structure.
-
-```yaml
-  ...
-  - file: subsection/index.md
-    children:
-      - file: subsection/page-one.md
-      - file: subsection/page-two.md
-```
-
-A `file` can only select siblings and more deeply nested files as its children. It can't select files outside its own subtree on disk.
-
-#### Hidden files
-
-A hidden file can be declared in the TOC. 
-```yaml
-  - hidden: developer-pages.md
-```
-
-It can't have any children and won't show up in the navigation.
-
-You can still [link to it locally](../../developer-notes.md).
-
-#### Nesting `toc`
-
-The `toc` key can include nested `toc.yml` files.
-
-The following example includes two sub-`toc.yml` files located in directories named `elastic-basics` and `solutions`:
-
-```yml
-toc:
-  - file: index.md
-  - toc: elastic-basics
-  - toc: solutions
-```
-
-### Attributes
-
-Example:
-
-```yml
-subs:
-  attr-name:   "attr value"
-  ea:   "Elastic Agent"
-  es:   "Elasticsearch"
-```
-
-See [Attributes](./attributes.md) to learn more.
-
-### `suppress`
-
-Optional list of diagnostic hint types to suppress for this navigation file. Available in both `docset.yml` and `toc.yml` files.
-
-Valid suppression values:
-
-- `DeepLinkingVirtualFile`
-- `FolderFileNameMismatch`
-- `AutolinkElasticCoDocs`
-
-Example:
-
-```yaml
-suppress:
-  - DeepLinkingVirtualFile
-  - FolderFileNameMismatch
-```
-
-#### `DeepLinkingVirtualFile`
-
-Suppresses hints about files with children that use deep-linking (path contains `/`).
-
-By default, the builder emits a hint when a file reference includes a path separator and has children:
-
-```yaml
-toc:
-  - file: a/b/c/getting-started.md
-    children:
-      - file: a/b/c/setup.md
-      - file: a/b/c/install.md
-```
-
-**Hint message**: "File 'a/b/c/getting-started.md' uses deep-linking with children. Consider using 'folder' instead of 'file' for better navigation structure. Virtual files are primarily intended to group sibling files together."
-
-**Why this is discouraged**: Virtual files (files with children) are intended to group sibling files together, not to create deep navigation hierarchies. Using `folder` structures provides clearer organization.
-
-**Preferred alternative**:
-
-```yaml
-toc:
-  - folder: a
-    children:
-      - folder: b
-        children:
-          - folder: c
-            children:
-              - file: index.md
-              - file: getting-started.md
-                children:
-                  - file: setup.md
-                  - file: install.md
-```
-
-Or use nested `toc.yml` files for better maintainability.
-
-#### `FolderFileNameMismatch`
-
-Suppresses hints about file names not matching folder names in folder+file combinations.
-
-By default, when using the folder+file pattern, the builder emits a hint if the file name doesn't match the folder name:
-
-```yaml
-toc:
-  - folder: getting-started
-    file: overview.md
-```
-
-**Hint message**: "File name 'overview.md' does not match folder name 'getting-started'. Best practice is to name the file the same as the folder (e.g., 'folder: getting-started, file: getting-started.md')."
-
-**Why this is discouraged**: Mismatched names can cause confusion about which file represents the folder's main content. Consistent naming makes navigation structure more predictable.
-
-**Preferred alternatives**:
-
-```yaml
-# Option 1: Match file name to folder name
-toc:
-  - folder: getting-started
-    file: getting-started.md
-
-# Option 2: Use index.md (always allowed)
-toc:
-  - folder: getting-started
-    file: index.md
-
-# Option 3: Use folder only with children
-toc:
-  - folder: getting-started
-    children:
-      - file: index.md
-```
-
-#### `AutolinkElasticCoDocs`
-
-Suppresses hints about autolinks pointing to elastic.co/docs URLs.
-
-By default, when the builder encounters a bare URL starting with `https://` that contains `elastic.co/docs`, it emits a hint suggesting to use crosslinks or relative links instead:
-
-```markdown
-See https://www.elastic.co/docs/solutions/search for more details.
-```
-
-**Hint message**: "Autolink points to elastic.co/docs. Consider using a crosslink or relative link instead."
-
-**Why this is discouraged**: Using [crosslinks](../../syntax/links.md) or relative links allows the documentation system to validate that the link target exists and enables proper URL handling across different environments.
-
-**When to suppress**: This hint can be useful to suppress when:
-
-- Processing generated content from external sources (for example, TOML files) that contain elastic.co URLs
-- During migration periods when converting large amounts of legacy content
-- For documentation that intentionally links to specific hosted versions
-
-**Preferred alternative**: Use crosslinks to reference other documentation:
-
-```markdown
-See [docs](docs-content://index.md) for more details.
-```
-
-### `cta`
-
-Defines named right-gutter call-to-action templates that pages can opt into via frontmatter.
-
-See [CTA](cta.md) for full configuration details and examples.
-
-## Navigation configuration patterns
-
-### Single file reference
-
-Reference a standalone file:
-
-```yaml
-toc:
-  - file: index.md
-  - file: getting-started.md
-  - file: api-reference.md
-```
-
-### File with children (virtual grouping)
-
-Group related sibling files under a parent file without creating a folder on disk:
-
-```yaml
-toc:
-  - file: getting-started.md
-    children:
-      - file: installation.md
-      - file: configuration.md
-      - file: first-steps.md
-```
-
-All children must be siblings of the parent file (in the same directory). The parent file can't select files outside its own subtree.
-
-### Folder without explicit children
-
-Include all markdown files in a folder automatically:
-
-```yaml
-toc:
-  - folder: api
-```
-
-All `.md` files in the `api/` folder will be included automatically. This is useful during development when the structure is still evolving.
-
-### Folder with explicit children
-
-Define exact files and their order within a folder:
-
-```yaml
-toc:
-  - folder: api
-    children:
-      - file: index.md
-      - file: authentication.md
-      - file: endpoints.md
-      - file: errors.md
-```
-
-When `children` is defined, all markdown files in the folder must be listed. The builder will error on dangling documentation files.
-
-### Folder and file combination
-
-Specify both a folder and a file to create a folder with a non-index entry point:
-
-```yaml
-toc:
-  - folder: getting-started
-    file: overview.md
-    children:
-      - file: installation.md
-      - file: configuration.md
-```
-
-Best practice: Use `index.md` or match the file name to the folder name to avoid `FolderFileNameMismatch` hints.
-
-### Nested toc reference
-
-Include a dedicated `toc.yml` file for large sections:
-
-```yaml
-toc:
-  - file: index.md
-  - toc: api-reference
-  - toc: tutorials
-  - toc: guides
-```
-
-Each `toc` reference loads the corresponding `toc.yml` file from that directory (for example, `api-reference/toc.yml`).
-
-### Mixed patterns
-
-Combine different patterns as needed:
-
-```yaml
-toc:
-  - file: index.md
-  - file: quick-start.md
-  - folder: guides
-    children:
-      - file: index.md
-      - folder: installation
-        file: installation.md
-        children:
-          - file: prerequisites.md
-          - file: steps.md
-  - toc: api-reference
-  - folder: troubleshooting
-```
+See [File structure](file-structure.md) for how directory layout maps to URLs.
diff --git a/docs/configure/content-set/toc-reference.md b/docs/configure/content-set/toc-reference.md
new file mode 100644
index 0000000000..b601b885d8
--- /dev/null
+++ b/docs/configure/content-set/toc-reference.md
@@ -0,0 +1,189 @@
+---
+navigation_title: TOC reference
+---
+
+# TOC reference
+
+The `toc` key in `docset.yml` and `toc.yml` defines the navigation tree for a content set. This page documents the syntax for each entry type. For layout patterns and when to choose each type, see [Documentation set navigation](../../building-blocks/documentation-set-navigation.md).
+
+File paths in `toc` entries are relative to the documentation set root (the folder containing `docset.yml`), not relative to the `toc.yml` file that declares them.
+
+## Entry types
+
+### `file`
+
+References a single Markdown file.
+
+| Sub-key | Type | Description |
+|---------|------|-------------|
+| `children` | list | Nested navigation entries. Children must be siblings or deeper files within the parent's subtree on disk. |
+
+```yaml
+toc:
+  - file: index.md
+  - file: getting-started.md
+    children:
+      - file: installation.md
+      - file: configuration.md
+```
+
+A `file` entry with `children` creates a virtual grouping that does not require a matching folder on disk. The builder may emit a `DeepLinkingVirtualFile` hint when the file path contains `/` and has children.
+
+### `hidden`
+
+References a page that is built and linkable but omitted from the navigation menu. Cannot have `children`.
+
+```yaml
+toc:
+  - hidden: developer-notes.md
+  - hidden: _search.md
+```
+
+### `folder`
+
+References a directory of Markdown files.
+
+| Sub-key | Type | Description |
+|---------|------|-------------|
+| `children` | list | Explicit list of files. When set, every `.md` file in the folder must be listed or the build errors. |
+| `sort` | string | Sort order for auto-discovered files: `asc`, `ascending`, `desc`, or `descending`. Default: ascending. Uses natural sort (`3_2_0` before `3_10_0`). `index.md` is always first. Ignored when `children` is set. |
+| `exclude` | list | File names to omit during auto-discovery (case-insensitive). Ignored when `children` is set. |
+| `file` | string | Entry-point file for the folder (folder + file combination). Creates a `FolderIndexFileRef`. |
+
+**Auto-discovery** (no `children`): all `.md` files in the folder are included automatically.
+
+```yaml
+toc:
+  - folder: api
+  - folder: api-versions
+    sort: desc
+    exclude:
+      - draft.md
+```
+
+**Explicit children:**
+
+```yaml
+toc:
+  - folder: api
+    children:
+      - file: index.md
+      - file: authentication.md
+```
+
+**Folder + file combination:**
+
+```yaml
+toc:
+  - folder: getting-started
+    file: getting-started.md
+    children:
+      - file: prerequisites.md
+      - file: installation.md
+```
+
+The builder may emit a `FolderFileNameMismatch` hint when `file` does not match the folder name (except for `index.md`).
+
+### `toc`
+
+References a nested `toc.yml` file in a subdirectory. Only `docset.yml` may reference `toc.yml` by default; nested `toc.yml` → `toc.yml` references require `max_toc_depth` > 2 in `docset.yml`.
+
+| Sub-key | Type | Description |
+|---------|------|-------------|
+| `children` | list | Optional children appended after the referenced TOC |
+
+```yaml
+toc:
+  - file: index.md
+  - toc: development
+  - toc: api-reference
+```
+
+Loads `development/toc.yml` and `api-reference/toc.yml`. The folder name is not repeated inside the nested `toc.yml`.
+
+### `crosslink`
+
+References a page in another documentation set. Requires the target repository in `cross_links`.
+
+| Sub-key | Type | Description |
+|---------|------|-------------|
+| `title` | string | Navigation label (required when using crosslink as a standalone entry) |
+| `hidden` | boolean | Omit from the navigation menu |
+| `children` | list | Nested entries under this cross-link |
+
+```yaml
+toc:
+  - file: index.md
+  - title: External Documentation
+    crosslink: docs-content://get-started/introduction.md
+  - folder: local-section
+    children:
+      - file: index.md
+      - title: API Reference
+        crosslink: elasticsearch://api/index.html
+```
+
+See [Outbound cross-links](../../building-blocks/outbound-cross-links.md) and [Links](../../syntax/links.md).
+
+### `cli`
+
+Embeds auto-generated CLI reference navigation from a JSON schema file.
+
+| Sub-key | Type | Description |
+|---------|------|-------------|
+| `cli` | string | Path to the CLI schema JSON, relative to `docset.yml` (required) |
+| `folder` | string | Supplemental Markdown docs folder |
+| `title` | string | Navigation title |
+| `navigation_title` | string | Short navigation label |
+
+```yaml
+toc:
+  - cli: cli-schema.json
+    folder: cli
+```
+
+See [CLI reference how-to](../../cli/cli-reference-how-to.md).
+
+### `detection_rules`
+
+Generates navigation from detection rule TOML files. Requires `extensions: [detection-rules]` in `docset.yml`.
+
+| Sub-key | Type | Description |
+|---------|------|-------------|
+| `file` | string | Overview Markdown page (required) |
+| `detection_rules` | list | Paths to folders containing rule TOML files (required) |
+| `deprecated_file` | string | Optional page for deprecated rules |
+| `children` | list | Additional navigation entries |
+
+```yaml
+toc:
+  - file: index.md
+    detection_rules:
+      - '../rules'
+```
+
+See [Extensions](extensions.md).
+
+## `suppress`
+
+Top-level key (not a `toc` entry type). Suppresses diagnostic hints for the navigation file. Available in both `docset.yml` and `toc.yml`.
+
+| Value | Triggers when |
+|-------|---------------|
+| `DeepLinkingVirtualFile` | A `file` with `children` uses a path containing `/` |
+| `FolderFileNameMismatch` | A `folder` + `file` pair has mismatched names |
+| `AutolinkElasticCoDocs` | A bare URL autolink points at `elastic.co/docs` |
+
+```yaml
+suppress:
+  - DeepLinkingVirtualFile
+  - AutolinkElasticCoDocs
+```
+
+See [`docset.yml` reference](docset-reference.md#suppress) for details.
+
+## Related topics
+
+* [`docset.yml` reference](docset-reference.md) — all top-level configuration keys
+* [Navigation layout](navigation.md) — patterns and trade-offs for structuring navigation
+* [Documentation set navigation](../../building-blocks/documentation-set-navigation.md) — worked examples
diff --git a/docs/contribute/add-repo.md b/docs/contribute/add-repo.md
index 882db70217..b61b07b08f 100644
--- a/docs/contribute/add-repo.md
+++ b/docs/contribute/add-repo.md
@@ -13,7 +13,7 @@ Follow these instructions to add a new docs repository.
 The new docs repository needs to satisfy these requirements:
 
 - The repository must have a `docs` folder in the root.
-- The `docs` folder must contain a valid [`docset.yml` file](../configure/content-set/navigation.md) and Markdown files.
+- The `docs` folder must contain a valid [`docset.yml` file](../configure/content-set/docset-reference.md) and Markdown files.
 - Markdown files within the `docs` folder that follow the V3 format. Refer to [Syntax](../syntax/index.md).
 - The repository must be within the Elastic organization on `GitHub` and public.
 
diff --git a/docs/migration/guide/automated.md b/docs/migration/guide/automated.md
index db2b5f0576..cfd73331f6 100644
--- a/docs/migration/guide/automated.md
+++ b/docs/migration/guide/automated.md
@@ -39,7 +39,7 @@ toc:
   - file: index.md
 ```
 
-For more information, see [Navigation](../../configure/content-set/navigation.md).
+For configuration keys, see [`docset.yml` reference](../../configure/content-set/docset-reference.md). For layout patterns, see [Navigation layout](../../configure/content-set/navigation.md) and [Documentation set navigation](../../building-blocks/documentation-set-navigation.md).
 
 ## Next steps