Treat childless file: subdir/index.md as a single-page folder

[cotti]

Why

Closes #764. Authors expect to add single-page subdirectories to the TOC with the natural full path:

toc:
  - file: reference/1password/index.md
  - file: reference/activemq/index.md

Instead, every such childless file: subdir/index.md entry was silently dropped from the navigation, with no error. The only workaround was the unintuitive folder: + file: index.md form (or renaming files to reference/1password.md).

What

A childless file: entry pointing at a subdirectory index.md previously resolved to a bare leaf that competed with its siblings for the parent's index slot — losing that race meant it never appeared in the tree (and in nested cases its path got doubled).

The YAML converter now treats such an entry as sugar for folder: subdir with a single file: index.md child, so it becomes its own single-page subsection and the full-path form works as documented. Entries that declare explicit children are untouched and keep their existing virtual-file (deep-linking) semantics, so the change is backward compatible.

Covered by new regression tests in DeepLinkedIndexFileTests.cs (conversion, backward-compat for bare index.md and entries with children, rendering as a plain link, multiple siblings under a parent folder, and no path-doubling under a virtual-file parent). Navigation behavior is documented under "Deep-linked index.md files" in the navigation config docs.

Made with Cursor

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 06685619-2b47-4b50-83b4-17b4574a4ab2

📥 Commits

Reviewing files that changed from the base of the PR and between 778baaa and 6e79b31.

📒 Files selected for processing (3)

• docs/configure/content-set/navigation.md
• src/Elastic.Documentation.Configuration/Toc/TableOfContentsYamlConverters.cs
• tests/Navigation.Tests/Isolation/DeepLinkedIndexFileTests.cs

🚧 Files skipped from review as they are similar to previous changes (3)

• src/Elastic.Documentation.Configuration/Toc/TableOfContentsYamlConverters.cs
• docs/configure/content-set/navigation.md
• tests/Navigation.Tests/Isolation/DeepLinkedIndexFileTests.cs

---

📝 Walkthrough

Walkthrough

The PR adds documentation for deep-linked index.md TOC entries and updates TocItemYamlConverter.ReadYaml so childless .../index.md entries become FolderRef values with a generated FolderIndexFileRef. Root index.md stays an IndexFileRef, and entries with explicit children keep virtual grouping behavior. New tests cover conversion, navigation rendering, and URL resolution.

Sequence Diagram(s)

sequenceDiagram
  participant TocEntry as docset.yml TOC entry
  participant Converter as TocItemYamlConverter.ReadYaml
  participant Navigation as navigation rendering
  participant Collector as error collector

  TocEntry->>Converter: file: reference/.../index.md
  alt childless deep-linked index.md
    Converter-->>Navigation: FolderRef with FolderIndexFileRef
  else bare root index.md
    Converter-->>Navigation: IndexFileRef
  else deep-linked entry with children
    Converter-->>Navigation: FileRef with children
  end
  Navigation-->>Collector: zero errors

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change to childless deep-linked index files.
Description check	✅ Passed	The description is directly about the same TOC navigation fix and its regression tests.
Linked Issues check	✅ Passed	The changes implement the requested full-path inclusion behavior for single-index subdirectories and preserve the stated backward compatibility.
Out of Scope Changes check	✅ Passed	The docs and tests added here support the navigation fix and do not introduce unrelated scope.

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch fix/764-deep-linked-index-files

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Mpdreamz]

Thanks for the fix — the implementation is correct and the test coverage is solid. A few things to address before merging:

Comment verbosity

The four-line comment block in TableOfContentsYamlConverters.cs re-narrates the bug history. That belongs in the commit/PR description, not the source. Trim to one line:

// Sugar: "file: subdir/index.md" without children → single-page folder to avoid silent nav drop.
if (children.Count == 0 && fileOnly.EndsWith("/index.md", StringComparison.Ordinal))

Docs framing

The PR description calls folder: + file: index.md "the unintuitive workaround" but that has always been the preferred canonical form. The docs section should reflect this — e.g.:

"This is shorthand for the explicit folder: + file: form, which remains the preferred approach for folders that also have additional children."

Missing docs: behavior under folder: + children:

The test FolderWithChildlessIndexFileChildrenKeepsEveryEntry shows the sugar works inside a parent folder's children: list too, but the docs don't mention it. This is the primary real-world use case (e.g. 100+ single-page integrations under a reference/ folder):

toc:
  - folder: reference
    file: index.md
    children:
      - file: 1password/index.md       # → becomes its own FolderRef
      - file: activemq/index.md        # → becomes its own FolderRef

Each entry becomes its own subsection; none "steals" the parent's index. Worth a short mention in the docs since it's the main usage pattern.

toc: version scope

The version: key goes through a separate converter branch. Please confirm whether file: subdir/index.md under a versioned toc entry is also covered (or explicitly out of scope). If it still silently drops there, that's worth a follow-up issue at minimum.

Minor: test class docstring

The class-level <summary> block in DeepLinkedIndexFileTests.cs is multi-paragraph. Project convention is no multi-paragraph docstrings — either drop it or fold to one line.

[cotti]

Thanks for the review @Mpdreamz — addressed in 778baaa (also rebased onto latest main):

• Comment verbosity — trimmed the block to a single line on the if.
• Docs framing — reworded so the folder: + file: form is presented as the preferred canonical approach, and the deep-linked form as shorthand for it.
• Missing docs (folder: + children:) — added a dedicated example showing the shorthand inside a parent folder's children: list (the dozens-of-integrations case), noting each child becomes its own subsection and none is consumed as the parent's index.
• Test class docstring — folded to one line.

On toc: version scope: I went looking for a separate versioned-toc converter branch and couldn't find one in this repo. All file: entries — top-level in docset.yml, nested under folder:/children:, and inside isolated sub-toc.yml files (IsolatedTableOfContentsRef) — are deserialized by the single TocItemYamlConverter.ReadYaml, so the sugar applies uniformly everywhere a file: entry is parsed. The only other TOC converter is SiteTableOfContentsRefYamlConverter for the assembler navigation.yml, but that branch only accepts whole-content-set toc:/path_prefix: references and never parses individual file: entries, so it's unaffected. Net: deep-linked index.md isn't silently dropped under any of these paths, so no follow-up issue seems warranted. If you were referring to a specific versioned-toc construct I'm not seeing (e.g. the changelog version: → target: normalization, which is unrelated to navigation), point me at it and I'll cover it.