docs: migrate from Mintlify to Docusaurus 3

[planetf1]

Fixes #1176
Fixes #557

👉 Live preview

Browse the site now: https://planetf1.github.io/mellea/

This is the full migration, deployed from planetf1/mellea on every push to main (on my fork). All 11 sidebar sections are live. Use it to review navigation, dark mode, search, and content before voting to merge.

---

What this does

This PR replaces the Mintlify documentation setup with a Docusaurus 3.10 site
that builds cleanly and deploys to GitHub Pages via a single CI job.

The content of docs/docs/ is preserved almost entirely — changes are purely
mechanical: canonical frontmatter removed, sidebarTitle renamed to
sidebar_label, a handful of admonitions updated to Docusaurus syntax, and
internal links de-prefixed to match the way Docusaurus strips numeric filename
prefixes from doc IDs (01-your-first-generative-program → your-first-generative-program).

The homepage has been simplified: the four lower card grids (How Mellea works,
Key patterns, Backends, How-to guides) are removed. They were teasers for content
that already lives in the sidebar — keeping only the four primary nav cards (Get
started, Tutorial, Code examples, API reference) gives a cleaner first impression.

Key design decisions

Single docs plugin, two named sidebars. Rather than two separate
@docusaurus/plugin-content-docs instances, the site uses one plugin with
routeBasePath: '/' and both docsSidebar and apiSidebar defined in
sidebars.ts. This avoids SSR failures at the secondary plugin's root route
when only a placeholder API doc exists.

apiSidebar is autogenerated. The docs/docs/api/ tree is wiped and
regenerated by the autogen pipeline on every CI run. A static {type:'doc'}
entry in the sidebar would be deleted on each build; {type:'autogenerated', dirName:'api'} picks up whatever the pipeline emits.

SidebarFix injection disabled. decorate_api_mdx.py was emitting a
Mintlify-specific import { SidebarFix } from "/snippets/SidebarFix.mdx"
into every generated API MDX file. Step 3 in decorate() is now a no-op.

<Icon> shim added. mdxify generates <Icon icon="github" .../> as a
source link in every API heading. An Icon MDX component shim is registered
globally; it renders the GitHub SVG and handles the string-form style
attribute that mdxify produces.

onBrokenLinks: 'throw', onBrokenAnchors: 'throw'. The Docusaurus build
fails on any broken internal link or anchor in static docs — this is stricter
than Mintlify, which ran cloud-side and didn't surface link failures in CI. The
generated API MDX files produce some cross-reference warnings that are pre-existing
and do not break the build today; fixing them requires autogen pipeline retargeting
(deferred, tracked in "What's deferred" below).

Fork/upstream base URL separation. DOCS_BASE_URL is set to /mellea/
when running on planetf1/mellea and / on generative-computing/mellea.

Visual polish from template comparison. Compared against the
sgd-docusaurus template prototype. Adopted: Prism github/dracula code themes,
article max-width (48rem), rich dark-mode backgrounds, navbar border separator,
uppercase sidebar section headers, increased line height. Kept: IBM Plex fonts,
monochrome primary palette, single-plugin routing.

Docs versioning is fully integrated into the release pipeline.
Docusaurus's built-in versioning is wired into publish-release.yml so the
docs lifecycle tracks the Python package lifecycle automatically — no manual
steps added to the release checklist.

For users: after the first final release ships, visiting docs.mellea.ai
lands on the latest released version by default. A version dropdown in the
navbar lets anyone switch to main (unreleased, labelled "main (unreleased)"
with a banner) or any prior release snapshot. Visiting today, before the first
snapshot, shows main (which is the only version).

For the release manager: nothing changes. Running publish-release.yml with
bump_type: final (or patch-final) now also triggers a new snapshot-docs
job that commits versioned_docs/version-X.Y.Z/ to main, sets that version
as the new default, and pushes. That push triggers docs-publish.yml via the
docs/** path filter, deploying production. No additional dispatch, no extra UI
step.

For GitHub/CI: the snapshot-docs job runs in the auto-release environment
(same bypass rights as the release job), checks out main, runs
docusaurus docs:version X.Y.Z, rewrites lastVersion in
docusaurus.config.ts via a small helper script, and pushes. The push commit
message (docs: snapshot X.Y.Z) triggers docs-publish.yml naturally. RCs and
dev bumps skip this job entirely (if: bump_type == 'final' || 'patch-final').

API reference source links use the correct git ref.
The GitHub source links rendered next to every function/class heading in the API
reference (View source / the GitHub icon) now resolve correctly:

• On a final release (X.Y.Z), links point to blob/vX.Y.Z/ — the exact
  tagged commit on GitHub.
• On main / dev / pre-release builds (.devN, rcN, etc.), links point
  to blob/main/ — the live default branch, which is the right target when no
  stable tag exists for that version.

Previously, dev builds produced blob/v0.7.0.dev0/ which 404s on GitHub
(PEP 440 pre-release suffixes have no corresponding git tag). The fix lives in
tooling/docs-autogen/build.py (normalize_version) and
tooling/docs-autogen/decorate_api_mdx.py (fix_source_links).

What's included

• docs/docusaurus.config.ts — full config: single-plugin setup, 63 Mintlify
  redirect rules, IBM Plex Sans typography, local search, analytics script;
  Docusaurus versioning config (lastVersion, versions.current,
  docsVersionDropdown in navbar)
• docs/sidebars.ts — 11-section manual sidebar plus autogenerated API sidebar
• docs/src/ — custom CSS, Mintlify shim components (Card, CardGroup, Icon,
  Note, Warning), global MDX registration
• docs/static/CNAME — docs.mellea.ai
• _category_.json for all 11 doc sections
• Autogen pipeline updated for Docusaurus mode
• CI workflow updated: Node 20, npm ci, Docusaurus build, deploy via
  peaceiris/actions-gh-pages
• .github/workflows/publish-release.yml — new snapshot-docs job (finals only)
• .github/scripts/set-last-version.mjs — helper to rewrite lastVersion on each release
• .github/scripts/release.sh — removed explicit docs-publish.yml dispatch for finals (now triggered automatically by the snapshot commit)
• RELEASE.md — updated to document automatic docs versioning behaviour
• tooling/docs-autogen/build.py — normalize_version fix for PEP 440 pre-releases
• tooling/docs-autogen/decorate_api_mdx.py — fix_source_links fix for correct v-prefix logic

Content validation

The build-and-validate CI job runs on every push and PR that touches docs/, mellea/, or the autogen tooling. Compared to Mintlify (cloud-hosted, no local build step — link failures were invisible in CI), Docusaurus adds transparent, local validation with explicit severity levels.

Hard failures — block CI

Check	How	What it catches
Broken internal links	onBrokenLinks: 'throw' in Docusaurus config	Any internal [link](path) that doesn't resolve to a real page
Broken anchors	onBrokenAnchors: 'throw'	Any #heading reference that doesn't exist on the target page
Duplicate routes	onDuplicateRoutes: 'throw'	Two pages resolving to the same URL (e.g. from a bad redirect)
Docstring quality gate	audit_coverage.py --quality --fail-on-quality --threshold 100 --orphans	Any public function with a raise statement missing a Raises: docstring entry; orphaned API pages
CLI reference tests	pytest tooling/docs-autogen/test_cli_reference.py	Autogenerated CLI reference page coherence
Docusaurus build	npm run build	TypeScript config errors, MDX parse failures, missing imports

Soft checks — recorded in job summary, non-blocking

Check	How	Notes
Markdownlint	markdownlint-cli on docs/docs/**/*.md	Style and formatting issues in hand-authored docs
API docstring coverage	audit_coverage.py --threshold 80	Warns if coverage drops below 80% but doesn't block

Pre-existing warnings (not regressions)

Warning	Source	Status
Broken links/anchors on /api/mellea/*	Generated API MDX cross-refs don't match Docusaurus route tree	Deferred — requires autogen retargeting
Broken links in tutorials/	Tutorial pages use numbered relative links (./01-foo) that Docusaurus strips	Pre-existing in source
Cannot infer update date	CI shallow checkout misses git history for generated files	Cosmetic, no impact
griffe type annotation warnings	Untyped parameters in source code picked up by the API doc generator	Pre-existing, unrelated to this PR

These warnings existed under Mintlify too — they just weren't visible because Mintlify's build was opaque to CI.

Going live (after merge — not part of this PR)

1. Enable GitHub Pages on generative-computing/mellea: Settings → Pages → gh-pages branch
2. Update docs.mellea.ai DNS CNAME from Mintlify to generative-computing.github.io
3. One-time bootstrap: run cd docs && npm run docusaurus -- docs:version X.Y.Z (using the current latest released tag) and commit the resulting versioned_docs/, versioned_sidebars/, versions.json, and lastVersion config edit to main. This creates the first snapshot so the version dropdown is populated before the next release fires.

What's deferred

• Full autogen pipeline retargeting (slug migration, sidebar TS emit, MDX
  cross-reference cleanup — root cause of the broken link warnings above)
• Algolia DocSearch, Cloudflare previews
• PR preview deploys for contributor PRs (no fork-based preview infrastructure)
• markdownlint-cli → markdownlint-cli2 bump

Testing

cd docs && npm ci && npm run build   # exits 0
npm run start                         # browse localhost:3000

Spot checks:

• All 11 sidebar sections expand correctly
• Dark mode toggles
• Local search returns results
• A sample redirect (e.g. /guide/glossary → /reference/glossary) works
• API Reference navbar item shows the generated API tree
• API source links on main point to blob/main/ (not a 404 tag URL)

[planetf1]

Merge coordination — DNS/CNAME cutover required

This PR is ready from a code and CI perspective, but it cannot be merged in isolation. Merging without coordinating the DNS change will cause a gap where docs.mellea.ai points to Mintlify but the gh-pages branch has already switched to Docusaurus, or vice versa.

The cutover steps (from the PR description) need to happen as a coordinated sequence:

1. Merge this PR
2. Confirm the gh-pages branch has been deployed successfully on generative-computing/mellea
3. Enable GitHub Pages on the repo (Settings → Pages → gh-pages branch)
4. Update docs.mellea.ai DNS CNAME from Mintlify to generative-computing.github.io
5. Verify the site is live at docs.mellea.ai before decommissioning Mintlify

There's also a bit more planning needed on the exact sequence — e.g. whether to keep Mintlify serving in parallel for a short overlap period, who holds the DNS access, whether there are any Mintlify-side redirects in flight that need to be replicated first.

Suggest we pick a short timeslot (30 min should be enough) where a few of us with DNS/GitHub Pages access are available to walk through this together. Happy to coordinate that once reviewers have signed off.

[planetf1]

TODO: docs staging/release lifecycle

The current setup deploys continuously from main to gh-pages with no staging gate. This works for now but leaves a gap worth addressing before we're fully settled on the new platform:

• No staging environment on generative-computing/mellea itself — the fork preview (planetf1.github.io/mellea/) filled that role for this PR but won't scale as a general pattern
• No versioned docs — the site always reflects main; there's no mechanism to serve docs pinned to a specific release (e.g. docs.mellea.ai/v0.4/)
• No preview deploys for contributor PRs — external contributors can't preview their doc changes without a fork setup
• Relationship to package releases is undefined — when a new Python release ships, should the docs deployment be gated or coordinated in any way?

This doesn't need to block this PR, but should be tracked as follow-on work once the Mintlify → Docusaurus cutover is complete.

[planetf1]

Update on the staging/release lifecycle TODO

Following up on the gap analysis above — this PR now addresses two of the four points:

✅ Versioned docs (now done): Docusaurus versioning is wired into `publish-release.yml`. From the next final release onwards, each `publish-release` dispatch with `bump_type: final` or `patch-final` automatically snapshots the current docs as `versioned_docs/version-X.Y.Z/`, updates `lastVersion`, and pushes to `main` — which triggers `docs-publish.yml` via the `docs/**` path filter. Production defaults to the latest release; a navbar dropdown gives access to `main` (unreleased) and any prior snapshot. No manual release-manager step needed.

✅ Relationship to package releases (now defined): Docs versioning is fully coupled to the Python release pipeline. RC bumps skip snapshot creation; only `final` and `patch-final` create a new default version. The bootstrap step (creating the first snapshot from the current latest tag) is documented in the PR description and needs to happen once after merge.

❌ Staging environment: still not addressed — no staging gate on `generative-computing/mellea` itself. The fork preview (`planetf1.github.io/mellea/`) remains the working substitute for this PR.

❌ PR preview deploys for contributor PRs: still not addressed. Needs separate infrastructure (e.g. Vercel/Netlify, or a dedicated `gh-pages` preview workflow per PR).

These two remaining items can be tracked as separate issues post-cutover.

[serjikibm]

Is the link main(unreleased pointing to docs that live on the main branch, while the base (docs.mellea.ai) will point to docs of a particular release?

[serjikibm]

The footer can use some updates. A couple of comments:

• The hover color for the links makes it unreadable
• The footer seems too much with sparse content.

I had something like below to make it less attention grabbing. But of course, it's just a matter of style, up to you. The hover color needs updating though, if kept the as is.

[serjikibm]

Minor UI update suggesstion

Current one

Alternative

In the current one the logo seems lonely :)

[planetf1]

Is the link main(unreleased pointing to docs that live on the main branch, while the base (docs.mellea.ai) will point to docs of a particular release?

All is hosted on the same github pages branch. The UI defaults to showing the last released version. The user can click that to get a dropdown of other versions including 'main (unreleased)'. That's a way around the separate staging site we had before and seems to be a common pattern.

Harder to properly test since we don't currently have a frozen release. Suggestion is we place close attention when we do the release...

[planetf1]

@serjikibm — footer fixes just pushed (commit e8180b71, preview at https://planetf1.github.io/mellea/):

1. Hover colour bug fixed — footer link hover was inheriting --ifm-color-primary: #000000 from light-mode, making text invisible on the dark #0d1117 background. Added explicit color: rgba(255,255,255,0.65) / :hover { color: #fff } overrides in custom.css that apply regardless of colour mode.

2. Footer column title added — the single links group had no title:, which left the logo floating above an untitled list. Added title: "Community".

3. Homepage hero layout — the 300 px standalone mascot image was creating a very tall sparse hero. Replaced with a side-by-side flex row (120 px logo + tagline text + install command), which should match the more compact layout in your alternative screenshot. Happy to adjust sizing if it is not quite right.