From 8ffcc2ee707ae4b4e1a07123441a6f2b56ece9a3 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 22 Aug 2026 01:51:57 +0000 Subject: [PATCH 01/12] Add WIP Astro Starlight prototype of the docs site Explores moving these docs off GitBook onto Astro Starlight, building to a static site suitable for Cloudflare Pages. The GitBook content at the repo root is untouched and remains the source of truth. site/scripts/gitbook_to_starlight.py reads it and generates the Starlight site; everything it writes is gitignored and regenerated by `npm run dev` / `npm run build`. The converter handles the GitBook-specific syntax automatically: hint blocks become Starlight asides, embeds become Vimeo/YouTube iframes and local video tags, SUMMARY.md becomes the sidebar, and relative .md links are resolved to absolute URLs. The landing page is hand-written, since GitBook's card table has no automatic equivalent. Five embeds pointed at files.gitbook.com CDN URLs that stop working once the GitBook space goes away; these are repointed at the local copies in .gitbook/assets. Builds 43 pages in ~5s including the Pagefind search index. See site/README.md for how to run it and what is still outstanding. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01HErYsDQFEjH6ErwV17HXSt --- site/.gitignore | 10 + site/README.md | 85 + site/astro.config.mjs | 28 + site/package-lock.json | 7043 ++++++++++++++++++++++++++ site/package.json | 17 + site/scripts/gitbook_to_starlight.py | 271 + site/src/content.config.ts | 7 + site/src/landing/index.mdx | 54 + site/src/styles/custom.css | 26 + 9 files changed, 7541 insertions(+) create mode 100644 site/.gitignore create mode 100644 site/README.md create mode 100644 site/astro.config.mjs create mode 100644 site/package-lock.json create mode 100644 site/package.json create mode 100644 site/scripts/gitbook_to_starlight.py create mode 100644 site/src/content.config.ts create mode 100644 site/src/landing/index.mdx create mode 100644 site/src/styles/custom.css diff --git a/site/.gitignore b/site/.gitignore new file mode 100644 index 0000000..9d8a819 --- /dev/null +++ b/site/.gitignore @@ -0,0 +1,10 @@ +# Build output and deps +node_modules/ +dist/ +.astro/ + +# Everything below is generated by `npm run convert` +src/content/docs/ +src/assets/ +public/assets/ +sidebar.json diff --git a/site/README.md b/site/README.md new file mode 100644 index 0000000..f62a4d7 --- /dev/null +++ b/site/README.md @@ -0,0 +1,85 @@ +# Kiln docs on Astro Starlight (WIP prototype) + +A working proof-of-concept port of these docs off GitBook and onto +[Astro Starlight](https://starlight.astro.build/), building to a static site +that can be hosted on Cloudflare Pages. + +The GitBook content in this repo is untouched. This directory reads it and +generates a Starlight site from it. + +## Try it locally + +Requires Node 20+ and Python 3. + +```sh +cd site +npm install +npm run dev +``` + +Then open . + +`npm run dev` runs the converter first, so a plain `npm install && npm run dev` +is all you need. To build the static site instead: + +```sh +npm run build # output in site/dist +npm run preview # serve site/dist locally +``` + +## How it works + +`scripts/gitbook_to_starlight.py` reads the GitBook markdown at the repo root +and generates Starlight content. Everything it writes is gitignored, so the +site is always regenerated from the GitBook files as the source of truth: + +| Generated | From | +| --- | --- | +| `src/content/docs/**` | `docs/`, `developers/` | +| `sidebar.json` | `SUMMARY.md` | +| `public/assets/**`, `src/assets/hero.png` | `.gitbook/assets/` | + +Re-run it on its own with `npm run convert`. + +What it converts automatically: + +- 81 `{% hint style="…" %}` blocks into Starlight asides (`:::note`, `:::tip`, + `:::caution`, `:::danger`) +- 14 `{% embed %}` blocks into Vimeo/YouTube iframes and local `