Skip to content

fix: drop mkdocs nav entries for notebooks the book never builds - #539

Merged
tschm merged 1 commit into
mainfrom
fix/book-nav-dangling-notebook-entries
Aug 24, 2026
Merged

fix: drop mkdocs nav entries for notebooks the book never builds#539
tschm merged 1 commit into
mainfrom
fix/book-nav-dangling-notebook-entries

Conversation

@tschm

@tschm tschm commented Aug 24, 2026

Copy link
Copy Markdown
Owner

Unblocks #538 (the rhiza v1.6.0 update), which fails book / build.

What's wrong

mkdocs.yml navigated to five notebook pages the book never builds:

- Notebooks:
    - Experiment1: notebooks/Experiment1.html
    ...

These have never resolved. Both paths are 404 on the live site right now:

  • https://tschm.github.io/cs/notebooks/Experiment1.html404
  • https://tschm.github.io/cs/marimo/notebooks/Experiment1.html404 (the path book/_toc.yml links to)

The book build has been saying so all along, in a warning nothing gated on:

[WARN] no marimo folder; skipping notebook export

rhiza-task exports notebooks from marimo_folder. This repo never sets it, so it
resolves to the CLI default docs/notebooks, which doesn't exist here — the notebooks
live under book/marimo/notebooks, which is named by source_folder. The export
no-ops, and the five nav entries dangle.

rhiza v1.6.0 adds a book-nav gate that checks every nav target against the built
site, which is what surfaced this:

[ERROR] nav target not in the built book: notebooks/Experiment1.html
...
failed  book-nav  5 of 12 nav target(s) missing from '_book'
        -- the site would publish a 404 in its own navigation

What this does

Removes the five entries, so the nav describes what the site actually publishes. The
remaining 7 nav targets all resolve. No other file changes.

What this deliberately does not do

Make the notebooks publish. That looks like a one-line marimo-folder setting, but it
isn't:

  • Both the exporter (folder.glob("*.py")) and rhiza_marimo.yml's matrix
    (find -maxdepth 1 -name "*.py") glob every Python file with no notebook filter.
  • book/marimo/notebooks also holds optimize.py and preamble.py, which are plain
    modules, not marimo notebooks, and carry no PEP 723 header. The matrix runs
    uv run --script on each match, so it would go from 0 jobs to 7 with 2 failures.
  • Separating them means moving preamble.py off the notebooks' sys.path, and all
    five notebooks plus optimize.py do from preamble import …. It would also touch
    the ty extra-paths headers, the 1:1 table in docs/development/TEST_LAYOUT.md,
    scripts/check_test_layout.py, and source_folder.

Worth doing as its own change if those pages should be on the site. Filed separately.

The `Notebooks:` nav section pointed at notebooks/Experiment1.html through
Experiment5.html. Those pages have never been built or published: both
https://tschm.github.io/cs/notebooks/Experiment1.html and the
marimo/notebooks/ path that book/_toc.yml references return 404 today.

The book build reports why, and has all along:

    [WARN] no marimo folder; skipping notebook export

`rhiza-task` exports notebooks from `marimo_folder`, which this repo leaves
unset. It therefore resolves to the CLI default `docs/notebooks`, which does
not exist here -- the notebooks live under book/marimo/notebooks, named by
`source_folder`. So the export no-ops and the five nav targets dangle.

rhiza v1.6.0 adds a `book-nav` gate that catches exactly this, which is what
surfaced it. Removing the entries makes the nav describe what the site
actually publishes.

Not fixed here: setting `marimo-folder` so the notebooks really do publish.
Both the export and rhiza_marimo.yml's matrix glob *.py with no notebook
filter, so pointing them at book/marimo/notebooks would also pick up
optimize.py and preamble.py, which are plain modules -- the matrix would run
`uv run --script` on files with no PEP 723 header and fail. Separating them
means moving preamble.py out of the notebooks' sys.path, which all five
notebooks and optimize.py import from. Left as follow-up work.
@coderabbitai

coderabbitai Bot commented Aug 24, 2026

Copy link
Copy Markdown

Warning

Review limit reached

Next included review available in 40 minutes.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a7aca609-c252-466e-923d-7e0c8117d987

📥 Commits

Reviewing files that changed from the base of the PR and between 2f58f2d and 6639a2d.

📒 Files selected for processing (1)
  • mkdocs.yml

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@tschm
tschm merged commit 11460de into main Aug 24, 2026
43 checks passed
@tschm
tschm deleted the fix/book-nav-dangling-notebook-entries branch August 24, 2026 15:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant