Documentation

[planetf1]

Where we are today

Mellea's docs site runs on Mintlify (v2, "maple" theme). The pipeline works as follows:

• Hand-authored MDX guides live in docs/docs/ on main, co-located with the source.
• A custom Python toolchain (tooling/docs-autogen/, driven by mdxify/griffe) generates the API reference from docstrings at build time.
• GitHub Actions (docs-publish.yml) assembles static + generated content and force-pushes it to orphan branches (docs/staging, docs/production, docs/preview). Mintlify reads from those branches.
• Navigation is declared in docs/docs/docs.json (Mintlify's config schema).
• Local preview: npx mintlify dev.

The pipeline is documented in detail in docs/PUBLISHING.md.

Known limitations

1. No doc versioning — issue Version Docs #557 is open. Mintlify's versioning story requires a paid plan tier and is structurally different from tools like MkDocs+mike. We currently publish a single "latest" view only.
2. SaaS dependency — staging and production environments are configured in the Mintlify dashboard (not in the repo). Environment setup is not reproducible without dashboard access.
3. Fork PR deploys are blocked — the deploy step requires write access to the upstream repo; fork contributors cannot trigger a docs preview from their PR.
4. MDX-specific tooling — the docs-autogen pipeline emits Mintlify-flavoured MDX (JSX components, docs.json nav schema). A switch to another tool would require retooling the generator.
5. Proprietary cost — Mintlify is a commercial product. As the project grows this is a factor.
6. Deferred improvements are accumulating switching cost — several open issues (e.g. Docs: Install steps in docs #757, install steps) are natural candidates for Mintlify-specific MDX components such as <Tabs>, <Card>, and <CodeGroup>. Every improvement we make using those components deepens the lock-in. The longer we defer this decision, the more migration effort accumulates — which is an argument for deciding sooner.

When the publish pipeline was first designed (issue #617), the comment was noted: "in the middle to long term, we also want to revisit the tooling we are using to publish the docs and where they are hosted." This discussion is that revisit.

The question

Do we continue with Mintlify, or migrate to an alternative stack?

Option A — Stay with Mintlify

Keep the current setup. Address versioning when it becomes a blocker (possibly via the mike-style multi-branch approach, manually). Acceptable if the team is satisfied with the hosted UX and the cost is not a concern.

Trade-offs: retained familiarity, no migration cost, Mintlify's component library (tabs, cards, code groups) is genuinely good; SaaS lock-in, no versioning without paid tier, fork deploy friction remains.

Option B — MkDocs + Material for MkDocs

The dominant choice in the Python open-source ecosystem (FastAPI, Pydantic, LangChain, smolagents). Fully open source. Docs hosted free on GitHub Pages. Native versioning via mike. API reference via mkdocstrings (griffe-based — compatible with our existing toolchain). Markdown-native; no JSX. Material's tab syntax (=== "Tab name") covers the same use cases as Mintlify's <Tabs>.

Trade-offs: excellent Python-ecosystem fit, zero cost, versioning built-in, fork PRs can deploy via standard GitHub Pages; migration effort (~days), less polished default UX than Mintlify.

Option C — Docusaurus

React-based, widely used outside the Python ecosystem (Meta, Vercel, etc.). Versioning built-in. GitHub Pages hosting.

Trade-offs: strong versioning and i18n story; heavier Node.js dependency, less natural fit for a Python project, more config overhead.

Option D — Nextra / other

Other emerging tools (Nextra, Starlight/Astro) are worth a look if the team has appetite, but are less established for Python API reference generation.

---

Thoughts? In particular:

• Is doc versioning a near-term priority, or can it wait?
• Is the Mintlify cost/lock-in a concern at current scale?
• Any strong preferences or prior experience with the alternatives?

[psschwei]

I would not use MkDocs + Material for MkDocs - the Material plugin has basically been more or less killed due to some issues between its creator and the mkdocs project.

[psschwei]

Is doc versioning a near-term priority, or can it wait?

My two cents is it can wait / may not even be needed (esp. as we don't actively maintain releases as per discussion in #1005 / #1076)

Is the Mintlify cost/lock-in a concern at current scale?

Not to my knowledge, but @serjikibm may have more details on the $$$

Any strong preferences or prior experience with the alternatives?

I've worked with material+mkdocs extensively, but that's a no-go due it being EOLed