Review requested: MkDocs Material 9 upgrade (preview site)

[kingthorin]

Summary

I have a fork preview of an MkDocs Material upgrade for the documentation site and would appreciate maintainer feedback before opening a PR.

Preview: https://kingthorin.github.io/datafaker/

Branch: kingthorin:material-update

The current production site runs a vendored copy of Material 8.1.3 checked into material/. The preview switches to pip-installed Material 9.7.6 and keeps only the small template overrides the site actually needs.

Why upgrade?

Smaller, easier-to-maintain repo

• Removes ~8,700 vendored theme files from git (including ~9,000 unused icon SVGs that were never referenced by the site).
• Net change on the branch is roughly −18,500 / +700 lines - most of the diff is deleting dead theme assets.
• Theme version is pinned in a new requirements-docs.txt; CI installs deps instead of relying on a frozen copy in the tree.
• Future Material upgrades become a dependency bump + smoke test, not a multi-thousand-file vendored merge.

Better reader experience

• Light / dark mode - palette toggle with prefers-color-scheme support (try the sun/moon control in the header).
• Much improved mobile layout - Material 9’s responsive navigation, search, and typography behave noticeably better on small screens than the 8.x vendored build.
• Release pages footer fix - navigation.footer adds previous/next links at the bottom of content pages and stops the awkward “floating” footer behaviour on long release note pages.
• Code blocks - one-click copy (content.code.copy).
• Edit links - "Edit this page” on GitHub (content.action.edit).
• Release nav - 2.x / 1.x sidebar groups still collapse as on production (navigation.sections stays off; Material 9 expands those groups when enabled).
• Homepage hero, announce bar, and site styling are preserved via material/overrides/ and docs/stylesheets/extra.css only.

Safer deploy pipeline

• deploy-docs.yml installs from requirements-docs.txt and runs mkdocs build --strict.
• Maintainer guide added at material/README.md - local dev (venv), deploy flow, upgrade checklist, and “never re-vendor the theme” guidance.
• NOTES.md points to that guide.

What to smoke-test on the preview

1. Homepage - hero, illustration, layout
2. Light ↔ dark toggle
3. A content page, e.g. Getting started - body text, code copy, edit link
4. Releases - footer prev/next, sidebar 2.x / 1.x collapse
5. Mobile or narrow viewport - nav drawer, search, tabs
6. Search and tab navigation

Next steps

If this looks good, I will open a PR from kingthorin:material-update → main with the preview URL in the description.

Happy to adjust anything - palette colours, which Material 9 features are enabled, nav behaviour, or scope of the initial PR. I'm

[kingthorin]

Update: homepage styling + social preview note

Homepage wave background: The first preview build accidentally dropped the custom hero CSS (SVG wave, purple gradient, white “Quick start” button) when the vendored Material 8 bundle was removed. That styling was never part of stock Material - it was site-specific CSS from the original landing-page setup. It has now been restored in docs/stylesheets/extra.css on material-update; the preview site will be redeployed shortly.

Social preview cards on the fork preview: Open Graph images are generated by the allscreenshots-og-screenshot plugin via og.allscreenshots.com. That service only renders screenshots for verified domains. www.datafaker.net is registered and works; kingthorin.github.io is not, so sharing the fork preview URL will not show OG images (DOMAIN_NOT_VERIFIED). This is a preview-host limitation only - production social cards should continue to work unchanged after merge.

[kingthorin]

Update: SNAPSHOT release notes excluded from published site

Snapshot release pages (docs/releases/*-SNAPSHOT.md) remain in the repo for the post-release version-updates workflow, but are no longer published to the docs site:

• exclude_docs in mkdocs.yml omits releases/*-SNAPSHOT.md from the build
• Releases nav no longer links snapshot entries (latest stable only)
• MkdocsReleaseNavUpdater updated accordingly

Preview redeployed from 35ee3238 - Releases sidebar should no longer show the SNAPSHOT entry.

Edit: there were other minor tweaks after that ⬆️

[kingthorin]

@bodiam this is primarily for you, in case you have any particular attachment to the current site implementation.