Maintainer reference for running, validating, and deploying the Zodex documentation site.

Local development

Install dependencies and start Astro:

cd docs
bun install
bun run dev

Astro serves the site locally, usually at:

http://localhost:4321

Files to edit

The docs site is isolated under docs/:

docs/src/data/docs.ts                site name, repo URL, navigation, categories
docs/src/pages/index.astro           overview page
docs/src/pages/docs/index.astro      grouped docs index
docs/src/pages/docs/[...slug].astro  article route
docs/src/pages/docs.md.ts            raw markdown docs index
docs/src/pages/docs/[...slug].md.ts  raw markdown page route
docs/src/content/docs/**/*.md        documentation pages
docs/src/styles/global.css           visual system
docs/src/styles/landing.css          landing-page style entrypoint
docs/src/styles/landing/*.css        semantic landing-page style sections
docs/scripts/deployment.test.mjs     deployment workflow guardrails

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

Validate the docs site

Run:

cd docs
bun run test:vercel
bun run check
bun run build

test:vercel protects the monorepo deployment filter, check catches Astro and TypeScript issues, and 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:

cd docs
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.

The Vercel project root is docs/, but the published /install.sh and /install.ps1 routes read the canonical repository-level scripts/install.sh and scripts/install.ps1. Vercel outside-root source access must remain enabled.

The Docs GitHub Actions workflow deploys production on main and publishes a Preview URL on same-repository pull requests, only when site source, build inputs, or either installer changes. Changes to Rust dependencies, application code, and unrelated CI workflows do not request a Vercel deployment. Automatic Vercel Git deployments are disabled; GitHub Actions owns the deployment decision.