mkdocs-literate-nav icon indicating copy to clipboard operation
mkdocs-literate-nav copied to clipboard

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

Open cdwilson opened this issue 6 months ago • 0 comments

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):

image

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

image

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 [email protected]: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)
image

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 [email protected]: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.

cdwilson avatar Aug 09 '24 23:08 cdwilson