WIP: Astro Starlight prototype — GitBook alternative

[scosman]

WIP / preview only. Opened for review of the approach, not to merge. Nothing here changes the existing GitBook content or site.

Explores moving these docs off GitBook onto Astro Starlight, building to a static site suitable for Cloudflare Pages.

Try it locally

Requires Node 22.12+ (Astro 7's floor) and Python 3.

cd site
npm install
npm run serve     # build + preview

Then open http://localhost:4321. npm run dev also works and rebuilds on change, but if the checkout lives in a file-syncing folder (Dropbox, iCloud Drive, OneDrive), the dev server can fail intermittently with module errors from inside node_modules/astro — npm run serve sidesteps that. See site/README.md → Troubleshooting.

Approach

The GitBook markdown at the repo root stays the source of truth. site/scripts/gitbook_to_starlight.py reads it and generates the Starlight site. Everything the script writes is gitignored and regenerated on every dev/build, so there is no second copy of the docs to keep in sync — this PR adds a handful of files, not 43.

Generated	From
src/content/docs/**	docs/, developers/
sidebar.json	SUMMARY.md
public/assets/**	.gitbook/assets/

Converted automatically:

• 81 {% hint style="…" %} blocks → Starlight asides (:::note / :::tip / :::caution / :::danger)
• 14 {% embed %} blocks → Vimeo/YouTube iframes and local <video> tags
• {% code %} wrappers stripped (Expressive Code covers those options)
• SUMMARY.md → sidebar, nested groups included
• Relative .md links → absolute site URLs, resolved per file
• Leading # Heading → Starlight title frontmatter

The ~90 <figure> blocks are left as raw HTML and render as-is, width attributes included.

Builds 43 pages in a few seconds, including the Pagefind search index — no Algolia or other external search service required.

python3 scripts/gitbook_to_starlight.py --list prints every source file it picks up without writing anything, for when the page count looks off.

Theme

Uses starlight-theme-black, a shadcn-inspired Starlight theme, which adds a top nav bar and a per-page "Copy page" menu with open-in-ChatGPT/Claude actions. Themes are Starlight plugins, so this is one entry in the plugins array and is straightforward to swap.

src/styles/custom.css carries the accent colors plus one workaround: the theme gives sidebar links a fixed 30px height against a 22.4px line-height, so labels wrapping to two lines overflow their box and collide with the next entry. Three of our sidebar labels hit this.

Two things found along the way

• Five {% embed %} blocks pointed at files.gitbook.com CDN URLs. Those stop working once the GitBook space goes away. Local copies exist in .gitbook/assets, and the converter repoints them.
• Two videos exceed Cloudflare Pages' 25 MiB per-file limit — final_1080.mp4 (38 MB) and final_1080p_web_fast_start.mp4 (27 MB). They need to move to Cloudflare Stream, R2, or Vimeo before this can deploy anywhere, independent of framework choice.

Not done

• The landing page (site/src/landing/index.mdx) is hand-written — GitBook's <table data-view="cards"> has no automatic equivalent. It is the one page maintained by hand rather than generated.
• Images skip Astro's optimizer; they are copied to public/assets/ and referenced absolutely. Moving them into src/assets/ with relative markdown links enables automatic WebP and responsive sizing (the hero image alone goes 63 kB → 2 kB through the pipeline).
• No redirects for any URLs that change relative to the current GitBook site.
• No WYSIWYG editor wired up. Starlight pairs with git-backed CMSes such as Keystatic or TinaCMS; that is a separate decision from the framework.

Full details and caveats in site/README.md.