Rendering 2-level hierarchies for `nav` may fail for jupytext-sync-ed notebooks

[jmp75]

Summary

I can observe some unexpected rendering behavior with 2nd level hierarchies for. I've tried my best to reduce to a clear repro, which may be only partial of what I observe across projects.

nav:
  - first:
    - Overview: index.md
    - Changelog: changelog.md
  - second:
    - tutorial_1: nb/tutorial_1.ipynb
    - tutorial_2: nb/tutorial_2.ipynb

Repro

I did not locate prior tests for the above, so I've set up a fork csiro-hydroinformatics/mkdocs-jupyter, with an added test yaml config featuring the hierarchy with two levels as above. See the permalink to the nav section, containing:

nav:
  - Home: 
    - Overview: index.md
    - Details: lvl2-content.md
  - Notebooks:
    - Demo (nb): demo.ipynb
    - Equations (nb): variational-inference.ipynb
    - Ruby (nb): ruby.ipynb
    - 2Demo (nb): subf/demo-2.ipynb
    - 2Equations (nb): subf/variational-inference-2.ipynb
    - 2Ruby (nb): subf/ruby-2.ipynb

Note that I initially thought this was due to the use of navigation.tabs features in the theme:

theme:
  name: material
  features:
  - navigation.sections
  - navigation.tabs
  - navigation.tabs.sticky

but the issue persists with these turned off as well. Screen captures below are with navigation features on.

Observations

After mkdocs serve, I have as expected two top tabs home and notebooks. If I click on the "Notebooks" tab , I see 6 level two subsections. Display defaults to the first demo.ipynb notebook, fair enough:

If I click on the second subsection, for variational-inference.ipynb, the left hand sidebar empties:

Clicking back to the tab links home or notebooks gets things back in order, and if I try to click on the fifth notebook, which is for subf/variational-inference-2.ipynb, whose content is almost identical to variational-inference.ipynb, the left hand sidebar displays an intuitive layout:

versions

As obtained with uv sync:

mkdocs==1.6.1
mkdocs-get-deps==0.2.0
-e file:///home/abcdef/src/mkdocs-jupyter
mkdocs-material==9.5.34
mkdocs-material-extensions==1.3.1

Browser: firefox and chrome.

Background

I wanted to focus on the repro above, but in case this provides context, this is where I am coming from:

I have a package doc with several tutorial notebooks rendered with mkdocs-jupyter there. It works as expected, and you can check the permalink to mkdocs.yml.

nav:
  - Home:
    - Overview: index.md
    - Changelog: changelog.md
  - tutorials:
    - tutorial_1: nb/tutorial_1.ipynb
    - tutorial_2: nb/tutorial_2.ipynb

I am trying to replicate this pattern for a new package geosdhydro. It works for a single notebook, but fails to behave correctly with several (only the first notebook can be navigated to). I am not entirely sure the repro above captures that last issue.

[jmp75]

While working around this I got a hunch that a root cause may be jupytext synchronised files side by side (blah.py, blah.ipynb).

Even if your nav section only uses the .ipynb file explicitly, you must use include: ["*.ipynb"] in the mkdocs-jupyter plugin config (or at least presumably exclude the .py files one way or another).

The issue may be closed, not sure - will leave the decision to maintainers.

More context, see mkdocs.yml permalink for full file:

# snip
nav:
  - Home:
    - Overview: index.md
    - Changelog: changelog.md
    # See https://github.com/danielfrg/mkdocs-jupyter/issues/251
    # important config for the plugin `mkdocs-jupytext` to not include .py files 
  - Examples:
    - basic_usage: nb/basic_usage.ipynb
    - lachlan : nb/lachlan.ipynb
    - load_lachlan : nb/load_lachlan.ipynb
  - API reference: reference/api.md

# snip

plugins:
- search
- autorefs
- mkdocs-jupyter:
    ignore_h1_titles: false
    # IMPORTANT: explicit include
    # Any jupytext sync-ed .py files alongside *.ipynb
    # and this will muck up the navigable hierarchy display.
    # relates to https://github.com/danielfrg/mkdocs-jupyter/issues/251
    include: ["*.ipynb"] 
    # ignore: ["some-irrelevant-files/*.ipynb"]
    execute: false
    show_input: true
    include_source: true