🚧 Prototype: unified Astro + Starlight docs site (Python + Rust)

[Roger-luo]

Draft / RFC — not for merge yet. Opening this early so everyone can see the direction and try it locally. Feedback very welcome.

What this is

A prototype of a new documentation website (website/, built with Astro 5 + Starlight) that unifies our Python and Rust API reference under one theme, one search box, and one version switcher — designed to grow with the ongoing Rust refactor (bloqade-lanes, bloqade-circuit, tsim, ppvm, … eventually one monorepo).

It lives alongside the current MkDocs site. Nothing about the existing site changes — the old workflows, mkdocs.yml, and docs/ are untouched and still deploy to production. This branch only adds files.

Why

• Serve Python + Rust docs today and absorb crates gradually, without waiting 6–12 months for the refactor to finish.
• Keep our proven "pin each package to the tag matching the installed version" aggregation, but generalize it so any repo (or a future in-monorepo crate) is just one manifest entry.
• Get versioning under control (downstream deps don't map 1:1 to the bloqade version).

🔍 See it locally

Requirements: Node ≥ 20 and pnpm. (The full API reference additionally needs uv and a Rust nightly toolchain.)

Quick preview — landing, guides, blog, and the design system (no Python/Rust needed)

# from the repo root
pnpm --dir website install
pnpm --dir website dev
# open the printed URL (e.g. http://localhost:4321)

This renders the landing page, all migrated guides, the blog, and the full theme/design — enough to review look-and-feel and navigation.

Full site including the versioned Python + Rust API reference

The per-version API pages are generated from pinned sources (and are gitignored, not committed), so generate them first, then serve:

# from the repo root
uv sync                       # installs bloqade + sub-packages so version pins resolve
pnpm --dir website install

# generate the API docs for the `dev` version — pick ONE:
#  (A) if you have sibling checkouts next to this repo (../bloqade-circuit, ../bloqade-analog, ../bloqade-lanes):
python website/scripts/build_versions.py --versions dev --prefer-local
#  (B) otherwise, clone the pinned tags from GitHub:
python website/scripts/build_versions.py --versions dev --clone-dir website/sources

# then serve (or build):
pnpm --dir website dev        # or: pnpm --dir website build

Notes:

• Rust API needs a nightly toolchain: rustup toolchain install nightly (used for cargo rustdoc --output-format json).
• Tutorials render statically by default; set EXECUTE_NOTEBOOKS=1 before building to execute them.
• A production build is pnpm --dir website build → output in website/dist/ (this is what CI publishes).

Live preview (once CI passes)

The newly-added workflows deploy this branch to an isolated gh-pages subpath so it can't touch the live site:

• branch → https://bloqade.quera.com/next/
• each PR → https://bloqade.quera.com/astro-preview/pr-<N>/

These workflows are brand new and may need a fixup pass on their first run — if the live preview isn't up yet, use the local steps above.

How it's built (architecture)

• Unified renderer. Two language-native emitters output MDX + frontmatter consumed by a shared component library (ApiModule/ApiClass/ApiFn/Signature/Params/…); Astro owns all presentation. Python via griffe (same lib mkdocstrings uses), Rust via rustdoc JSON.
• Aggregation. website/docs.sources.toml lists each API source as a repo pinned by tag (pin-from:<pkg> → uv pip show) or a local monorepo path=. Adding ppvm = one entry; flipping a source to an in-repo path later changes nothing else.
• Cross-references. <ApiXref> resolves against a merged inventory; the build emits a Sphinx-compatible objects.inv (so downstream Sphinx projects can intersphinx to us). Optional strict mode (XREF_STRICT=1) fails the build on broken refs.
• Versioning. Single distribution axis = the bloqade meta-version, plus an auto-generated compatibility matrix (bloqade X → circuit/analog/lanes/tsim). Only /api is versioned; landing/guides/blog are evergreen. /api-scoped version switcher.
• Search. Unified Pagefind index across guides, blog, landing, and API symbols.
• One design system. A single token layer feeds both the custom landing/blog and every Starlight --sl-* variable; header, footer, and widgets (cards, callouts, tabs, code blocks) are shared/consistent — no default Starlight look.
• CI. .github/workflows/website-*.yml build in GitHub Actions and publish via website/scripts/publish.sh (a thin seam; swapping to Vercel --prebuilt later is one line).

Current build: 744 pages, all cross-refs resolved, objects.inv emitted.

Not done yet (intentionally)

• Cutover (redirects from old URLs, switching production from MkDocs, /api/latest/<symbol> deep-link aliasing) — a separate step once we're happy.
• Full tutorial/example migration — one tutorial (ghz) is migrated as a proof; the rest is the gradual "move things over" work.
• API signature panels use a slightly different radius than the shared card language (mkdocstrings parity) — easy to align if we want.

Feedback wanted

• Overall direction (Astro + Starlight, unified emitters).
• The versioning model (distribution axis + compatibility matrix).
• Anything that feels off in the design once you run it locally.

🤖 Generated with Claude Code

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://QuEraComputing.github.io/bloqade/pr-preview/pr-367/
Built to branch gh-pages at 2026-07-17 04:14 UTC. Preview will be ready when the GitHub Pages deployment is complete.