01 · Planning
How it started
Section titled “How it started”“you know those documentation template site right ?”
The conversation opened with documentation-template platforms — ReadMe, Mintlify, GitBook, Docusaurus, VitePress, MkDocs… — and the follow-up narrowed it to:
“what about starlight”
Starlight is Astro’s official documentation theme. Key points covered:
- Zero-config docs: drop
.md/.mdxinsrc/content/docs/and get sidebar, search, TOC, dark mode - Content collections with typed frontmatter (schema validation at build time)
- Ships zero JS by default, islands where interactivity is needed
- Built-in Pagefind search, i18n, breadcrumbs, prev/next, code copy buttons
- Extensible via Starlight plugins; free, open-source, no SaaS lock-in
- Natural fit here because the stack (Astro) was already familiar
Decision: Starlight ✅
Section titled “Decision: Starlight ✅”Docs-focused, lighter than Docusaurus, more opinionated than raw Astro, everything stays in the repo.
Free hosting research
Section titled “Free hosting research”“where can it be run for free”
Starlight builds static HTML, so “run for free” = host dist/ anywhere. Compared:
| Host | Free tier | Notes |
|---|---|---|
| GitHub Pages | Unlimited | yourname.github.io; already used for Yonko |
| Cloudflare Pages | 500 builds/mo, unlimited bandwidth | Picked — best for docs, global CDN, preview URLs |
| Netlify | 100 GB/mo, 300 build min/mo | Easiest; existing site there |
| Vercel | 100 GB/mo | 1-click from GitHub |
| GitLab Pages / Surge | Free | Fine but niche |
Reasoning
Section titled “Reasoning”Docs pages are content-heavy; the unlimited bandwidth of Cloudflare Pages means heavy code-sample pages cost nothing. The Astrogon template later turned out to ship a Cloudflare adapter + wrangler.jsonc — confirming the platform choice.
The architecture idea
Section titled “The architecture idea”“can we put the code and the data in github in a private repo and set up ci cd pipeline and a methodology like agile scrum or whatever and deploy from another platform than github pages since it’s a private repo”
Answer: yes, and that’s the right setup. Key clarifications recorded:
- Private repos + third-party hosts are not a conflict. Cloudflare/Netlify/Vercel connect to private repos via their own authenticated accounts — the repo never needs to be public. Only GitHub Pages has an awkward relationship with private repos.
- CI = quality gate (
npm ci && npm run build), CD = deploy on push tomain. - Scrum natively in GitHub: Issues (backlog) + labels, Milestones or Project Iterations (sprints), a Project board (Backlog → Ready → In Progress → Review → Done) with automated card moves, and branch protection (PR required + CI must pass).
- Private docs = auth gate: static hosts don’t do auth by themselves, but Cloudflare Access (free for up to 50 users) in front of a Cloudflare Pages site gives login-gated docs for $0.
Decision: Cloudflare Access for privacy ✅
Section titled “Decision: Cloudflare Access for privacy ✅”The only fully free private-docs path found. Later confirmed when a foreign Access gate taught us the inverse (see 05 · The Name-Collision Mystery).
Templates reviewed
Section titled “Templates reviewed”“astrogon, pure, astro templates do you know thsees ? yes it will be private docs”
| Template | What it is | Verdict |
|---|---|---|
Astrogon (astrogon/astrogon, MIT) |
Multipurpose Astro + Tailwind + React template — SaaS landing, docs collections, blog, KaTeX, search | ✅ “just be the public doc” |
Pure (cworld1/astro-theme-pure) |
Blog & docs theme, ~870★, Pagefind, UnoCSS | ❌ “forget about Pure” (not a fit — blog+docs combo wasn’t wanted) |
| Starlight | Docs-only framework | ✅ “will be the private doc” |
Final architecture (user’s words)
Section titled “Final architecture (user’s words)”astrogon, just be the public doc — starlight will be the private doc — both will also run locally
| Site | Template | Visibility | Local port (dev) |
|---|---|---|---|
| Public docs | Astrogon | Public | 4321 |
| Private docs | Starlight | Login-gated | 4322 |