When the nav section is added to mkdocs.yml, the rendering of the navigation.path is broken

[milovanovicdusan]

After successfully installing the latest Material for MkDocs Insiders version, I configured the breadcrumbs navigation by specifying the navigation.path feature in the mkdocs.yml file. The breadcrumbs navigation was successfully rendered above the title of each page, as expected (see an example page below):

After that, I configured site navigation by specifying the nav section in the same mkdocs.yml file. Then, surprisingly, the breadcrumbs navigation got rendered differently (see example on the same page as above):

As you can see from the two snapshots above, the difference in rendering of the breadcrumbs navigation , before and after adding the nav section, is as follows:

• BEFORE nav was added: rendering of the whole navigation path, starting with the home page (named here Association Episteme), ending with the name of the menu item pointing to the current (opened) page (Open Source Intelligence)

• AFTER nav was added: rendering of only part of the path, omitting the home page and the current (opened) page

On further testing the functionality of rendering the breadcrumbs navigation before and after adding the navsection to the mkdocs.yml, I discovered that partial rendering only works for the pages belonging to second-level menu items that have children menu items/pages and for their third- and fourth-level children menu items. Furthermore, the path is not rendered fully compared to the rendering before adding navsection - the home page (Association Episteme in the snapshot below) and the current (opened) page are omitted.

The following snapshots probably best illustrate how the rendering of the breadcrumbs navigation works when the nav section is included in the mkdocs.yml:

1. No rendering of the breadcrumbs navigation for pages associated with the first-level menu item:
   
   

2. No rendering of the breadcrumbs navigation for pages associated with those second-level menu items that have no children (third-level) menu items:
   
   

3. Rendering only part of the breadcrumbs navigation path for pages associated with those second-level menu items that have children (third-level) menu items:
   
   

4. Rendering only part of the breadcrumbs navigation path for pages associated with the third-level menu items:
   
   

Is this an issue to be reported or an expected functionality for which I could not find any trace in the latest Material for MkDocs documentation or on the Web? The nav section, maintained by MkDocs, and breadcrumbs, maintained by Material for MkDocs, are handy for many reasons. It would be great if both worked as they should when used together.

Workaround

I found a dirty workaround to keep full rendering of the breadcrumbs path and organise menu items from left to right and up to down in the top and left navigation menus, respectively. I am using leading spaces in the names of the docs/ subdirectories to have them sorted not by name, as is the MkDocs default, but as I need them to appear on the web pages. That resulted in an ugly web address, where the leading spaces are URL-encoded as %20.

[squidfunk]

Could be a bug, could be misconfiguration. As mentioned earlier, we need a proper bug report with a minimal reproduction.

[squidfunk]

So, a quick fix of the instructions could be helpful, although I wouldn't insist too much on it. Maybe the info plugin could ignore venv/instead, and the issue should require specifying the exact environment used to run the dev server and build.

The info plugin already goes at great lengths to do that, as it is far from simple, sadly. We'll investigate once we find some time, thanks for the explanation!

[kamilkrzyskow]

Only the active virtual environment will be excluded, that's python -m venv venv and later source venv/bin/activate or venv\Scripts\activate on Windows.

So maybe Dusan had 2 venv directories the old one and new one, but let's assume he correctly created a new directory and used mkdocs new . As there are files in the venv it looks like the pip install properly targets the directory, so it should have been activated.
Maybe there is some issue with mkdocs build being registered globally to another Python installation and it runs outside of the activated venv 🤔

We could try to guess if a directory is an inactive virtual environment, based on the structure like bin/python or Scripts\python.exe
Or we could validate the PYTHONPATH environmental variable is in a directory which is a sibling of docs 🤔

[milovanovicdusan]

@kamilkrzyskow,

If this helps, here are three answers to your assumptions:

• I only had one venv/ directory in the working directory where I prepared the reproduction
• I am using the file system on macOS, not Windows
• I run mkdocs build from the activated venv within the working directory where docs/ directory and mkdocs.yml reside

[kamilkrzyskow]

@milovanovicdusan
Thanks for clarifying and your patience.

Personally I don't have access to macOS, so I would need to debug it on GitHub Actions CI.
Also the info plugin should generate a platform.json file which contains info about working directory and sys.path.
Maybe you could notice something amiss there 🤔

I should probably also include the site.PREFIXES there for easier debugging 🤔

EDIT: I'm currently looking at different past issues, and found this one:

• Privacy plugin: Long Kroki diagram URLs #8175

"cwd": ".../docs/mre",
"sys.path": [
  ".../docs/.venv/bin"
  ".../docs/.venv/lib/python3.13/site-packages"
]

In case of this user the docs/.venv path is not inside of docs/mre so there was no need to exclude it, but this shows there is enough information to debug this.

EDIT2: Actually, when I was doing a clean up of all my opened windows, I once again looked at the archive, and I saw that the issue above does also contain a .venv directory 😆 I was too focused on opening the platform.json to notice it before 🤦

So the root path, the current working directory was different than the path to the virtual environment, therefore the .venv got included in the zip. The question is, if that's a bug in detecting the cwd path or it was a case where they forgot to activate the new venv.

[kamilkrzyskow]

I found some older threads where it was mentioned that bash could possibly cache the executable.

• Config value 'plugins': The "blog" plugin is not installed mkdocs/mkdocs#3897 (reply in thread)
• plugin autorefs installed but not found mkdocs/mkdocs#3686 (comment)

So perhaps one of my initial ideas could be the case:

Maybe there is some issue with mkdocs build being registered globally to another Python installation and it runs outside of the activated venv 🤔

So either hash -r could help, or maybe it's a good idea to enforce creating the reproduction with python -m mkdocs build instead of mkdocs build