Docs site maintenance

Local development

Install dependencies and start Astro:

bun install
bun run dev

Astro serves the site locally, usually at:

http://localhost:4321

Files to edit

The docs site lives next to the Rust project:

src/data/docs.ts                site name, repo URL, navigation, categories
src/pages/index.astro           overview page
src/pages/docs/index.astro      grouped docs index
src/pages/docs/[...slug].astro  article route
src/pages/docs.md.ts            raw markdown docs index
src/pages/docs/[...slug].md.ts  raw markdown page route
src/content/docs/*.md           documentation pages
src/styles/global.css           visual system

Use src/content/docs for most documentation changes. Use src/pages/index.astro for the overview narrative and product positioning.

Validate the docs site

Run:

bun run check
bun run build

check catches Astro and TypeScript issues. build verifies static output and route generation.

Keep generated files out of commits

The repository ignores:

node_modules/
.astro/
dist/

Commit source files, lockfiles, and content. Do not commit local build output.

Deployment

The site builds to static output in dist and can be deployed by any static host:

bun run build

Use the host’s static output setting:

dist

When the docs site is deployed behind a custom domain, keep the repository link pointed at https://github.com/amxv/zodex.