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.