Skip to content

feat(docs): split the landing from the docs, migrate to Astro + Starlight - #5

Open
neogenz wants to merge 2 commits into
mainfrom
feat/split-landing-docs
Open

neogenz wants to merge 2 commits into
mainfrom
feat/split-landing-docs

Conversation

@neogenz

@neogenz neogenz commented Aug 18, 2026

Copy link
Copy Markdown
Owner

Splits the single-page docs site into a marketing landing at / and a documentation section at /docs, and moves the whole site from Next.js to Astro 7 + Starlight.

No library code changes: projects/ziflux/ is untouched by this branch.

What changes

  • Landing (/) — recomposed around the 60-second decision: hero with a live navigation/mutation demo, freshness summary, "not a fit", prior art, AI skills, closing CTA.
  • Documentation (/docs) — the old single reference page becomes 9 Starlight pages: overview, quick start, guide, caching, use cases, patterns, testing, API reference, gotchas.
  • Platform — Astro 7 + Starlight replaces Next.js 16. Brings Pagefind search, a sidebar, per-page TOC, a generated sitemap, llms.txt, and a "Copy page" action, none of which existed before.
  • Identity — Archivo + Sometype Mono, an orange accent tuned to meet WCAG AA in both themes.

Every section deleted from the old landing is re-homed rather than dropped: freshness → caching, scenarios → use cases, advanced-usage → patterns, copy-page-dropdown → the Starlight page-context plugin, callout → Starlight <Aside>.

Verification

  • pnpm check — 0 errors, 0 warnings, 0 hints across 19 files
  • pnpm build — 11 pages, Pagefind index, sitemap
  • All 20 internal links and 6 anchors resolve against the build output
  • API reference checked against the source: cachedResource overloads (defaultValue narrows value()), the public staleTime / expireTime getters, the Ctrl/Cmd+Shift+Z devtools shortcut, and logOperations defaulting to true in dev
  • Only navigation-demo and copy-button are interactive, and both sit inside client:* islands

Before merging

docs/vercel.json only takes effect if the Vercel project's Root Directory is set to docs. Worth confirming on the dashboard, otherwise the first production deploy after merge fails.

Known benign build warning: Entry docs → 404 was not found. Starlight falls back to its built-in 404 and dist/404.html is generated correctly. Adding src/content/docs/404.md would silence it and give a written 404 instead.

The Starlight migration flattened two JSX diagrams into ```text blocks:
the architecture flow in the guide and the cache-key tree in caching.
Both are back as styled markup, so they render as diagrams rather than
preformatted text, and the key tree no longer carries malformed glyphs.

Markdown code spans instead of raw <code> elements, because SmartyPants
rewrites quotes in raw HTML children and turned ['order'] into curly
quotes.

Also drops two "use client" directives left over from Next.js — inert
under Astro's React integration.
CLAUDE.md still described the docs site as Next.js + shadcn/ui.

.depot/ holds a generated CI migration proposal, not the live workflows,
so it stays out of the tree.
@vercel

vercel Bot commented Aug 18, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
ziflux-docs Ready Ready Preview Aug 18, 2026 9:28am

This branch was successfully deployed

1 active deployment
Preview — b169f7c7 Deployed Aug 18, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant