chore(deps): unpin mkdocs-material, require click>=8.4 for docs

[tschm]

This pull request was authored by a coding agent.

📝 Summary

Closes #10334

The docs group pinned mkdocs-material==9.6.20 with:

# Live reloading broken in >= 9.6.21: https://github.com/squidfunk/mkdocs-material/issues/8478
"mkdocs-material==9.6.20",

That pin treats a symptom. 9.6.20 is just the last release that capped click<8.2.2 — the incidental click cap was doing the work, not anything about the theme. mkdocs-material dropped that cap in 9.6.21, which is why live reload appeared to break there.

The actual bug is in click. MkDocs declares --no-livereload / --livereload as a feature switch group — two flag_value options sharing one parameter name, where only the second carries default=True:

@click.option('--no-livereload', 'livereload', flag_value=False, help=no_reload_help)
@click.option('--livereload', 'livereload', flag_value=True, default=True, hidden=True)

click 8.3.0 started dropping that explicit default when a sibling without one was declared first, so mkdocs serve silently came up with live reload off. click 8.4.0 fixed it, per its changelog:

Fix feature switch groups (several flag_value options sharing one parameter name) silently dropping an explicit default when a sibling option without an explicit default was declared first. Arbitration is now within ParameterSource.DEFAULT, an option that received an explicit default= keyword wins over a sibling whose default was auto-derived.

Bisected in a scratch mkdocs project to confirm:

click	live reload
8.2.1	ON
8.3.0	OFF
8.3.1	OFF
8.3.2	OFF
8.3.3	OFF
8.4.0	ON
8.4.2	ON

So this requires click>=8.4 in the docs group and lets mkdocs-material float from >=9.7.5 (the release that drops the pymdown-extensions~=10.2 cap and adds a mkdocs<2 cap). No --livereload workaround is needed and make docs-serve is unchanged.

Why this matters beyond the docs

Because uv resolves all dependency groups together, the ==9.6.20 pin was holding click at 8.2.1 and pymdown-extensions at 10.x across the entire workspace — including the test and dev environments. marimo's own runtime dependency is click>=8.0,<9, so CI has never exercised the click 8.3/8.4 that users actually get. After this change the workspace resolves click 8.4.2.

It also unblocks CI coverage for #10332 (relaxing the pymdown-extensions cap to allow 11.x) — with the pin in place, that cap could be relaxed but the resolver would still pick 10.x, so CI would never test 11.x. These two PRs are independent and can merge in either order; together they let CI resolve pymdown-extensions 11.x.

Verification

• mkdocs build --strict passes on both 9.6.20 (baseline) and 9.7.7 — exit 0 each time. The only new console output on 9.7.7 is upstream's informational MkDocs 2.0 banner, which squidfunk notes does not affect strict builds (confirmed).
• mkdocs serve --clean — the existing docs-serve target verbatim, no extra flags — reports Watching paths for changes: 'docs', 'mkdocs.yml', 'marimo' on click 8.4.2.
• pytest tests/ -k "not test_cli" (~11k tests) and pytest tests/_cli/test_cli_* show no new failures on click 8.4.2 versus 8.2.1. (Two pre-existing failures on both: test_openapi_up_to_date, and a cluster in tests/_code_mode/ that comes from my own user-level ~/.config/marimo/marimo.toml.)
• Rendered HTML: 235/236 pages differ, but only as markup normalization (self-closing tags, whitespace), a Font Awesome 7 icon bump, and social meta tags moving from name="twitter:*" to property="twitter:*". All upstream theme changes, no content or structural differences.

One thing worth a maintainer's eye: that name="twitter:*" → property="twitter:*" change is upstream's doing, but social card previews on docs.marimo.io are user-visible, so it may be worth a spot check with a card validator after merge.

I could not fully reproduce the CI docs environment locally (my machine needed DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib for cairosvg to find libcairo for the social plugin), so the strict-build results above come from a locally patched environment rather than the CI image.

📋 Pre-Review Checklist

• For large changes, or changes that affect the public API: this change was discussed or approved through an issue, on Discord, or the community discussions. — Dev-tooling only; no public API change.
• Any AI generated code has been reviewed line-by-line by the human PR author, who stands by it.
• Video or media evidence is provided for any visual changes (optional).

✅ Merge Checklist

• I have read the contributor guidelines.
• Documentation has been updated where applicable, including docstrings for API changes — n/a; the reasoning is captured in the pyproject.toml comment that replaces the old one.
• Tests have been added for the changes made — n/a; this is a dependency-constraint change, covered by the existing mkdocs build --strict docs CI job.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
marimo-docs	Ready	Preview, Comment	Jul 25, 2026 7:44pm

[Copilot]

Pull request overview

Updates the documentation dependency set to address MkDocs live-reload behavior by constraining click appropriately, while allowing mkdocs-material to float again (instead of being pinned), so the workspace can resolve newer docs-stack dependencies.

Changes:

• Replace the mkdocs-material==9.6.20 pin with a floating mkdocs-material>=9.7.5.
• Add a click>=8.4 requirement in the docs dependency group to avoid MkDocs live-reload issues seen with click 8.3.x.