Migrate the docs site from Quarto to Astro Starlight - #112
Merged
Conversation
The site was using Quarto as a plain static site generator: 23 pages of pure markdown, no executable chunks, stock cosmo theme. This replaces it with an Astro Starlight project in the same site/ directory (now a pnpm workspace member), with a product-style landing page and a zinc design system matching the app chrome, in light and dark. - Content converted qmd -> md/mdx with slugs preserved; callouts become Starlight asides, screenshots move to src/assets for optimization, custom heading anchors kept via remark-heading-id - starlight-links-validator fails the build on broken internal links; Pagefind search and a sitemap come with Starlight - Old .html URLs redirect via meta-refresh stubs in public/ - docs.yml builds with pnpm instead of Quarto; workflow_dispatch from a branch builds without deploying - scripts/screenshots.mjs default --out follows the images move
Starlight's content spacing rule adds margin-top to every grid child after the first, so the first card in each row sat 1rem higher than its neighbors.
tgerke
added a commit
that referenced
this pull request
Jul 23, 2026
Migrate the docs site from Quarto to Astro Starlight
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The Quarto site had become a plain static site generator: 23 markdown pages, no executed code, stock cosmo theme. The landing page read as academic project docs, and for an EDC the front page carries much of the credibility argument. Starlight matches the TypeScript monorepo, ships search, dark mode, and sidebar navigation, and lets the landing page look like a product.
What changed
site/is now an Astro Starlight project and a pnpm workspace member. All 23 pages converted from.qmdwith slugs preserved; Quarto callouts became Starlight asides, screenshots moved tosite/src/assets/screenshots/so Astro optimizes them, and the custom heading anchors survive via remark-heading-id..htmlURLs get meta-refresh stubs inpublic/(e.g./edc-core/tour.htmlredirects to/edc-core/tour/).docs.ymlbuilds with pnpm instead of Quarto; deploy is gated to main, so a branchworkflow_dispatchvalidates the build without publishing.scripts/screenshots.mjsdefault--outfollows the image move. CONTRIBUTING.md and CLAUDE.md path references updated.Verification
pnpm --filter site buildis green with the links validator clean (25 pages).pnpm lintandpnpm typecheckpass with site in the workspace.workflow_dispatchof docs.yml on this branch: run 30026686153, success.To preview locally:
pnpm install && pnpm --filter site dev, then open http://localhost:4321/edc-core/.