Astro's base option was set to /docs to anticipate the reverse-proxy
URL at checkmate.so/docs. Vercel serves the dist folder at the root,
which made every page 404 because Astro had baked /docs/ into every
internal link and asset URL.
## Changes
- Remove base: "/docs" from astro.config.mjs — site now serves at root
- Update Releases nav link to /releases
- Update README's reverse-proxy snippet to strip the /docs prefix
before forwarding to Vercel
## Final URL behaviour
- Direct: https://<vercel-domain>/ → Introduction
- Direct: https://<vercel-domain>/releases/ → Releases
- Proxy: https://checkmate.so/docs/ → strip /docs → Introduction
- Proxy: https://checkmate.so/docs/releases/ → strip /docs → Releases
Vercel's "Root Directory" setting limits the upload to docs/api/, so
the build cannot read sibling paths like ../../server/openapi.json or
../api-content/. A small prebuild script copies both into a vendored
folder inside the project tree (gitignored).
## Changes
- Add scripts/sync-sources.mjs to copy /docs/api-content/ and
/server/openapi.json into docs/api/src/vendored/ before dev/build
- Wire predev/prebuild npm scripts so the sync runs automatically
- Update astro.config.mjs and src/content.config.ts to read from the
vendored paths
- Gitignore src/vendored/ — contributors still edit the originals
## Changes
- Bump @astrojs/starlight to ^0.32.0 so starlight-openapi 0.13's plugin
contract (top-level setup hook) is supported
- Replace the no-arg docsLoader call with Astro's glob loader pointing
at ../api-content so prose stays outside the Astro project tree
- Rename introduction.md → index.md and update the sidebar slug so the
/docs/ root resolves instead of returning 404
- Commit package-lock.json so Vercel installs deterministically
## Verification
- npm run build produces 96 pages (7 narrative + 88 OpenAPI operations + 1
releases timeline)
- /docs/, /docs/releases/, /docs/api-reference/operations/authlogin/ and
every other route return 200 locally
- 14 release cards render with the brand-green "Latest" badge on v3.7.1
## Changes
- Add a Releases tab to the top navigation via a custom Starlight
Header override (HeaderLinks.astro)
- Add ReleaseCard.astro — Vercel/Linear-style entry with sticky date
+ version on the left, headline and feature bullets on the right
- Curate 14 release entries spanning v1.0 (Sept 2024) through v3.7.1
(April 2026), each focused on the most important user-facing
features rather than every commit
- Newest release carries a "Latest" badge in the brand color
- Mobile layout collapses the two-column timeline to a single column
## Benefits
- Visitors can see at a glance what shipped recently and what
Checkmate has matured into over time
- The data file (src/data/releases.ts) is the only thing that needs
editing when a new version ships — no template or styling churn
- Built on the same Starlight site as the API docs, so look and feel
stay consistent
## Changes
- Add narrative API documentation in docs/api-content/ (introduction,
quickstart, authentication, conventions, errors, rate limiting)
- Scaffold Astro Starlight site at docs/api/ that consumes prose from
the sibling api-content folder and auto-generates the endpoint
reference from server/openapi.json via starlight-openapi
- Wire Checkmate brand color (#13715B) into Starlight via custom CSS
- Add vercel.json so the docs site deploys cleanly as an Astro project
with root directory docs/api/
## Benefits
- Public API docs ready to publish at checkmate.so/docs
- Endpoint reference stays in sync with the OpenAPI spec automatically
- Zero third-party SaaS dependency: site is fully self-hosted on Vercel
- Contributors edit plain markdown; no Astro knowledge needed for prose
gorkem-bwl