regression: Enabling the plug-in messes up items as written in `SUMMARY.md` from `mkdocs-literate-nav`

llucax commented 10 months ago

Moving https://github.com/squidfunk/mkdocs-material/issues/5971 here as my next most likely cause of a regression we are experiencing.

Context

After upgrading from mkdocs-material 9.1.x to 9.2.x we started to see an issue with the nav bar.

I'm using mkdocs-literate-nav and this plugin to generate the nav bar. If I remove mkdocs-section-index from the plugin list in mkdocs.yml, the problem also goes away.

Bug description

$ cat docs/SUMMARY.md 
* [Home](index.md)
* [API Reference](reference/)
* [Contributing](CONTRIBUTING.md)

With mkdocs-material 9.1.21 or older, I get this:

(Note the API Reference, the correct version)

With mkdocs-materia 9.2.0 or newer, I get this:

(Note the sdk, the version with an unexpected text)

Unless I remove the mkdocs-section-index plugin, in which case I get the expected result again.

Steps to reproduce

$ git clone -b v0.25.0 https://github.com/frequenz-floss/frequenz-sdk-python.git
Cloning into 'frequenz-sdk-python'...
...
Turn off this advice by setting config variable advice.detachedHead to false

$ cd frequenz-sdk-python/
$ python3.11 -m venv .venv # Note only Python 3.11 is supported by this project
$ . .venv/bin/activate
$ pip install -e .[dev-mkdocs]
...
$ pip freeze | grep mkdocs
mkdocs==1.5.2
mkdocs-autorefs==0.5.0
mkdocs-gen-files==0.5.0
mkdocs-literate-nav==0.6.0
mkdocs-material==9.2.5
mkdocs-material-extensions==1.1.1
mkdocs-section-index==0.3.5
mkdocstrings==0.22.0
mkdocstrings-python==1.6.2
$ mkdocs serve
... deprecations ...
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Doc file 'SUMMARY.md' contains an unrecognized relative link 'reference/', it was left as is.
INFO    -  Documentation built in 3.20 seconds
INFO    -  [13:51:19] Watching paths for changes: 'docs', 'mkdocs.yml', 'src', 'README.md', 'CONTRIBUTING.md'
INFO    -  [13:51:19] Serving on http://127.0.0.1:8000/
WARNING -  [13:51:21] "GET /versions.json HTTP/1.1" code 404
INFO    -  [13:51:21] Browser connected: http://127.0.0.1:8000/

Check http://127.0.0.1:8000/ and observe the "sdk" in the menu (bad).

$ # edit mkdocs.yml
$ git diff
diff --git a/mkdocs.yml b/mkdocs.yml
index 13fe0f1..4d29795 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -115,7 +115,6 @@ plugins:
             - https://typing-extensions.readthedocs.io/en/stable/objects.inv
             - https://watchfiles.helpmanual.io/objects.inv
   - search
-  - section-index

 # Preview controls
 watch:
$ mkdocs serve
... deprecations ...
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Doc file 'SUMMARY.md' contains an unrecognized relative link 'reference/', it was left as is.
INFO    -  Documentation built in 3.72 seconds
INFO    -  [15:41:04] Watching paths for changes: 'docs', 'mkdocs.yml', 'src', 'README.md', 'CONTRIBUTING.md'
INFO    -  [15:41:04] Serving on http://127.0.0.1:8000/
WARNING -  [15:41:07] "GET /versions.json HTTP/1.1" code 404
INFO    -  [15:41:07] Browser connected: http://127.0.0.1:8000/reference/frequenz/sdk/actor/

Check http://127.0.0.1:8000/ and observe the "API Reference" in the menu (good).

Alternative re-enable the plugin and downgrade mkdocs-material:

$ git reset --hard
$ pip install mkdocs-material==9.1.21
Collecting mkdocs-material==9.1.21
  Obtaining dependency information for mkdocs-material==9.1.21 from https://files.pythonhosted.org/packages/c0/d3/abe920304e9dc6af40d4fd20f520c0ea64e9518fea259114e4f0956b975d/mkdocs_material-9.1.21-py3-none-any.whl.metadata
...
Installing collected packages: mkdocs-material
  Attempting uninstall: mkdocs-material
    Found existing installation: mkdocs-material 9.2.5
    Uninstalling mkdocs-material-9.2.5:
      Successfully uninstalled mkdocs-material-9.2.5
Successfully installed mkdocs-material-9.1.21
$ pip freeze | grep mkdocs
mkdocs==1.5.2
mkdocs-autorefs==0.5.0
mkdocs-gen-files==0.5.0
mkdocs-literate-nav==0.6.0
mkdocs-material==9.1.21
mkdocs-material-extensions==1.1.1
mkdocs-section-index==0.3.5
mkdocstrings==0.22.0
mkdocstrings-python==1.6.2
$ mkdocs serve
... deprecations ...
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Doc file 'SUMMARY.md' contains an unrecognized relative link 'reference/', it was left as is.
INFO    -  Documentation built in 3.17 seconds
INFO    -  [13:56:53] Watching paths for changes: 'docs', 'mkdocs.yml', 'src', 'README.md', 'CONTRIBUTING.md'
INFO    -  [13:56:53] Serving on http://127.0.0.1:8000/
WARNING -  [13:56:56] "GET /versions.json HTTP/1.1" code 404
INFO    -  [13:56:56] Browser connected: http://127.0.0.1:8000/

Check http://127.0.0.1:8000/ and observe the "API Reference" in the menu (good).

oprypin commented 10 months ago

Thanks for the amazing report. Tests actually caught this, here's the transition: https://github.com/oprypin/mkdocs-section-index/actions/runs/5922584405 https://github.com/oprypin/mkdocs-section-index/actions/runs/5935059657 it's just that I fell behind on following tests :grimacing:

llucax commented 10 months ago

Thanks for addressing it so quickly!

llucax commented 10 months ago

I saw in a related mkdocs-material issue comment that the theme already support a similar feature. I'm considering switching to the theme feature, which I guess is less likely to get out of sync. Is there anything this plugin offers that navigation.indexes doesn't?

oprypin / mkdocs-section-index