diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..ca67823 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.specs_skill_state/ 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..9411e19 --- /dev/null +++ b/site/README.md @@ -0,0 +1,167 @@ +# 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 22.12 or newer** (Astro 7's floor — older Node fails with +confusing module errors) 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 +``` + +## Theme + +The site uses [starlight-theme-black](https://github.com/adrian-ub/starlight-theme-black), +a shadcn-inspired Starlight theme. On top of stock Starlight it adds a top nav +bar and a per-page "Copy page" menu with open-in-ChatGPT/Claude actions. + +Starlight themes are plugins, so it is configured in one place — the `plugins` +array in `astro.config.mjs` — and swapping it is an npm install plus editing +that array. + +### Sidebar + +By default the theme renders a flat sidebar: every group becomes a static +header with all its children always visible, and `collapsed` in the sidebar +config is ignored. Our `SUMMARY.md` has six nested groups that need to expand +and collapse, so the theme is configured with `sidebar: { useDropdowns: true }` +in `astro.config.mjs`, which renders groups as collapsible dropdowns with a +caret in the theme's own styling. + +A group starts open if it contains the current page or is not marked +`collapsed`, so the section you are reading is always expanded. + +`src/styles/custom.css` carries one workaround for that sidebar. The theme +gives 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 labels are long enough to wrap. Letting the box grow fixes it, +but the theme's `8px` block padding then makes every row `38px`, so the +padding is traded down to keep the intended `30px` rhythm: single-line rows +stay at `30px` and wrapped ones grow to `53px`. + +The build also logs `No data found for font family Geist Mono`, from the +theme's font configuration. It is harmless — the monospace stack falls back — +and unrelated to the sidebar. + +## 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 `