Documents appear in root menu despite being hidden in folder (navigation behavior)

[theletterf]

Describe the bug

From a Slack discussion: When navigating the documentation, some documents (e.g., 'autopilot.md' in 'user-guide', 'admin-configure-sso.md' in 'admin-guide') appear in the root menu even though they are nested in folders and referenced as hidden in the folder structure YAML:

- folder: user-guide
  children:
    - hidden: autopilot.md

- folder: admin-guide
  children:
    - hidden: admin-configure-sso.md

These folders do not have an index, which might be related. There is additional behavior where only the first folder links its index, after which no others have referenced indexes. There is some confusion as to whether the folder overrides the hidden property, and it's unclear whether docs-builder is behaving as expected or if this is a bug.

See Slack thread for more details and context. If needed, I can provide more reproduction steps or examples.

Expected behavior

Documents referenced as hidden in folder configuration should not appear in the root menu. Folders without an index should not impact hidden children being excluded from navigation. Hidden items should remain hidden regardless of parent folder configuration.

Steps to reproduce

1. Add a folder to the navigation config (e.g., 'user-guide') with children marked as hidden: autopilot.md.
2. Repeat for another folder (e.g., 'admin-guide') with a hidden child.
3. Ensure neither folder has an index.md.
4. Build docs and check navigation menu: hidden files appear in the root menu instead of being excluded.

Based on the Slack thread, also review behavior when some folders have index.md and others do not.

Tooling

true,false,false

View original Slack conversation