[Mpdreamz]

The configure reference now says that nested toc.yml files accept suppress: too, how far it reaches, and when to restructure to folder: instead.

Affects: Configuration, Authoring

Prompt summary: Document that suppress: is valid in nested toc.yml files and not only docset.yml, with its scope and the three hint names, and fix the stale comment on TableOfContentsFile.SuppressDiagnostics. This supports the diagnostic-noise cleanup in https://github.com/elastic/docs-eng-team/issues/1115 (part of).

Why

docs/documentation/isolated/configure/index.md describes suppress: for docset.yml only, yet TableOfContentsFile.SuppressDiagnostics reads it from toc.yml as well. The XML comment on that property lists two of the three HintType values.

What

Where suppress: applies

The docs now state that suppress: is valid in docset.yml and in nested toc.yml files. A toc.yml list covers only the entries in that file, and a toc.yml does not inherit the docset.yml list. AutolinkElasticCoDocs is raised during Markdown parsing, so it is only read from docset.yml.

Preferring folder: over suppressing

The DeepLinkingVirtualFile section recommends folder: with file: index.md, and warns that a folder: with explicit children must list every Markdown file or the build fails with "is not listed in the table of contents". It also notes that the move can change URLs.

XML comment

TableOfContentsFile.SuppressDiagnostics now lists all three hint types. This is a comment-only change. The hardcoded docs-content list in DocumentationSetFile.cs is untouched.

Verify

Scratch docset with docset.yml (file: top/deep.md with children) and a nested sub/toc.yml (file: other/x.md with children). Run:

docs-builder build --path <docset> --output <out> --force --skip-cross-links

Without suppress:, two uses deep-linking with children hints appear (other/x.md and top/deep.md). With suppress: [DeepLinkingVirtualFile] added to sub/toc.yml, only the top/deep.md hint remains. dotnet build src/Elastic.Documentation.Configuration succeeds.

🤖 Generated with Claude Code

[github-actions]

Docs preview (local build)

Handbook preview: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/4559/

Sample changed pages:

• docs/documentation/isolated/configure/index.md

[infra-vault-gh-plugin-prod]

Severity: P3 (Low)

folder: with file: index.md does not auto-discover the other Markdown files, even when children is omitted. The YAML converter inserts the index as an explicit child, so folder resolution skips auto-discovery. Following this example in a multi-page folder therefore produces the same unlisted-page errors warned about here. Recommend a bare folder: for auto-discovery, or include the remaining pages as explicit children.

_{Generated by Libra. React with 👍 or 👎 to give feedback on this comment.}