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]

Warning

Review limit reached

@cotti, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 31 minutes and 16 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 96af7e4f-faa9-4d0d-bd94-d715ab90e76f

📥 Commits

Reviewing files that changed from the base of the PR and between d115285 and 83724b0.

📒 Files selected for processing (3)

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

✨ 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 and usage tips.}