Page is missing in nav when `navigation.indexes` is enabled

[cdwilson]

Issue Summary

When using the literate-nav plugin with navigation.indexes enabled, the page in my SUMMARY.md is missing from the nav (the page is instead linked to the Section above instead):

I expected that the page would be displayed in the nav like this:

How to reproduce

Originally, I was attempting to use the Automatic code reference pages recipe, but instead of using mkdocs-section-index, I enabled the built-in navigation.indexes feature from MkDocs Material.

As a test, I tried documenting a minimal Python package that only contains a single __init__.py file:

sandbox_mkdocs_python/
  __init__.py

This results in the following generated files:

docs/
├── index.md
└── reference
    ├── SUMMARY.md
    └── sandbox_mkdocs_python
        └── index.md

where SUMMARY.md contains:

* [sandbox_mkdocs_python](sandbox_mkdocs_python/index.md)

My nav in mkdocs.yml looks like this:

nav:
  - Get Started:
      - index.md
  - Code Reference: reference/

Here's the exact steps to reproduce the example described above:

git clone -b cdwilson/issues/literal-nav-navigation-indexes git@github.com:cdwilson/sandbox-mkdocs-python.git
cd sandbox-mkdocs-python/
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install hatch
hatch run doc:serve

Interestingly, the page does show up in the nav if any other file is added.

For example,

docs/
├── index.md
└── reference
    ├── SUMMARY.md
    └── sandbox_mkdocs_python
        ├── index.md
        └── test.md <- Add this file

Add the file to SUMMARY.md:

* [<code class="doc-symbol doc-symbol-nav doc-symbol-module"></code> sandbox_mkdocs_python](sandbox_mkdocs_python/index.md)
    * [test](sandbox_mkdocs_python/test.md)

Finally, the page also shows up if I use mkdocs-section-index instead of navigation.indexes.

Here's a variation of the previous example that uses section-index:

git clone -b cdwilson/issues/literal-nav-section-index git@github.com:cdwilson/sandbox-mkdocs-python.git
cd sandbox-mkdocs-python/
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install hatch
hatch run doc:serve

I'm not really sure why the page is getting merged into the Section above it when navigation.indexes is enabled, and was wondering if there was a way to prevent this from happening.

[frankkusters]

I'm not a maintainer, but I'd like to pitch in.

I think this behavior is caused by navigation.indexes. It collapses an index page into its parent section. If the parent section is otherwise empty, implicitly the parent section itself becomes an index page. This repeats until a parent section is encountered which is not otherwise empty.

In your example:

1. reference/sandbox_mkdocs_python/index.md is collapsed into the section reference/sandbox_mkdocs_python/.
2. Which is otherwise empty, so it is collapsed into reference/.
3. Which is also otherwise empty, so it is collapsed again, showing your document as "Code Reference" in the nav.

This also explains why adding reference/sandbox_mkdocs_python/test.md 'fixes' it: the section reference/sandbox_mkdocs_python/ is no longer empty, so won't be collapsed into reference/. My guess is that adding an extra file to reference/ would also work around the issue.

I also think this is intended behavior (although I can't find a reference for that right now).

Here's the code in mkdocs-material (follow the indexes variable):
https://github.com/squidfunk/mkdocs-material/blob/9.5.50/src/templates/partials/nav-item.html#L104