Skip to content

01 · Planning

“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/.mdx in src/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

Docs-focused, lighter than Docusaurus, more opinionated than raw Astro, everything stays in the repo.


“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

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.


“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 to main.
  • 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).


“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”

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