Add missing reference details for docset.yml and toc.yml

docs/_docset.yml

@@ -1,4 +1,4 @@
 project: 'doc-builder'
 max_toc_depth: 2
 # indicates this documentation set is not linkable by assembler.
 # relaxes a few restrictions around toc building and file placement
@@ -122,6 +122,8 @@
       - 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

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.

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
 

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}

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:

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