Checkmate/docs/api-content

Checkmate API documentation

Public-facing API documentation that powers https://checkmate.so/docs.

The site is built with Astro Starlight — a static-site generator that produces a fast, modern docs site with zero JavaScript by default. Starlight is open source and self-hostable; there is no third-party account required to publish.

Repository layout

docs/
├── api-content/          ← markdown prose (this folder — edit here)
│   ├── introduction.md
│   ├── quickstart.md
│   ├── authentication.md
│   ├── conventions.md
│   ├── errors.md
│   ├── rate-limiting.md
│   └── api-reference/
│       └── overview.md
└── api/                  ← Astro Starlight project (build tool — leave alone unless changing the site)
    ├── package.json
    ├── astro.config.mjs
    ├── src/content.config.ts
    └── src/styles/checkmate.css

Contributors editing prose only need to touch docs/api-content/. Astro's content loader picks up the markdown automatically.

The endpoint reference (every URL + schema) is auto-generated from server/openapi.json via the starlight-openapi plugin. Adding or changing an endpoint means updating that JSON; the public docs pick it up on the next Vercel build.

Local preview

cd docs/api
npm install
npm run dev

Visit http://localhost:4321/docs. Hot-reload works for markdown changes in docs/api-content/.

To produce the static site:

npm run build      # outputs docs/api/dist/
npm run preview    # serve the built output locally

Deploying to checkmate.so/docs

Astro Starlight builds a static site. Deploy on Vercel and reverse-proxy checkmate.so/docs/* to it.

One-time Vercel setup

1. Go to https://vercel.com → New Project → import the bluewave-labs/Checkmate GitHub repo.
2. Root Directory: set to docs/api.
3. Framework Preset: Vercel auto-detects Astro from vercel.json.
4. Build & Output: leave defaults (npm run build → dist/).
5. Production Branch: develop.
6. Deploy. Vercel returns a URL like checkmate-docs.vercel.app.
7. Verify the site renders correctly.

The deployment auto-rebuilds on every push to develop and on every PR (as a preview deploy).

Reverse-proxy /docs to Vercel

In whichever edge proxy fronts checkmate.so, route /docs/* to the Vercel deployment.

Cloudflare Workers:

addEventListener("fetch", (event) => {
  const url = new URL(event.request.url);
  if (url.pathname === "/docs" || url.pathname.startsWith("/docs/")) {
    const target = new URL(url.pathname, "https://checkmate-docs.vercel.app");
    target.search = url.search;
    return event.respondWith(fetch(target.toString(), event.request));
  }
});

nginx:

location /docs/ {
    proxy_pass https://checkmate-docs.vercel.app/docs/;
    proxy_set_header Host checkmate-docs.vercel.app;
    proxy_ssl_server_name on;
}

The base: "/docs" setting in astro.config.mjs ensures every internal link and asset URL is prefixed correctly so the site works at checkmate.so/docs/... rather than the root.

Updating the docs

Task	What to edit
Fix a typo, clarify wording	docs/api-content/*.md
Add a new narrative page	Add the file to docs/api-content/, then add a slug entry to astro.config.mjs → sidebar
Fix something in the API reference	Edit server/openapi.json (or the route spec it's built from) — never edit the generated reference pages
Change branding / colors	docs/api/src/styles/checkmate.css
Change site config (title, logo, social)	docs/api/astro.config.mjs

Two rules:

1. Never hand-edit the API reference. It's regenerated on every build. Fix the spec.
2. Test code samples against a real instance before merging. Wrong code in docs is worse than missing code.

Why Astro Starlight (and not Mintlify, Docusaurus, etc.)

• No third-party account required. Self-hostable on any static host.
• Best looking of the modern docs frameworks per multiple 2026 reviews — Distr, among others, migrated away from Docusaurus specifically for Starlight's design.
• Zero JavaScript by default. Pages are pure HTML — fast load, perfect Lighthouse scores.
• OpenAPI integration is first-class via starlight-openapi.
• Markdown is the source of truth. No proprietary formats. Easy to migrate later if needed.