docs(api): add public API documentation site (Astro Starlight)

## 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
This commit is contained in:
gorkem-bwl committed 2026-05-22 10:21:10 -04:00
1 parent 9027707c92
commit 9aa2594df7
16 files changed
+991

No files matched your search

+5
View File
@@ -0,0 +1,5 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 32" fill="none">
<rect x="2" y="6" width="20" height="20" rx="4" fill="#13715B"/>
<path d="M7 16l3.5 3.5L17 12" stroke="white" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"/>
<text x="30" y="22" font-family="-apple-system, BlinkMacSystemFont, 'Inter', sans-serif" font-size="18" font-weight="600" fill="currentColor">Checkmate</text>
</svg>

After

Width:  |  Height:  |  Size: 424 B

+13
View File
@@ -0,0 +1,13 @@
import { defineCollection } from "astro:content";
import { docsLoader } from "@astrojs/starlight/loaders";
import { docsSchema } from "@astrojs/starlight/schema";
// Load markdown from a sibling folder so prose lives outside the Astro
// project tree. Contributors edit /docs/api-content/*.md without touching
// the build tool.
export const collections = {
docs: defineCollection({
loader: docsLoader({ base: "../api-content" }),
schema: docsSchema(),
}),
};
+23
View File
@@ -0,0 +1,23 @@
/* Checkmate brand colors layered on top of Starlight defaults. */
:root {
--sl-color-accent-low: #0e5a48;
--sl-color-accent: #13715b;
--sl-color-accent-high: #1a8a6f;
--sl-color-white: #ffffff;
--sl-color-gray-1: #eef2f0;
--sl-color-gray-2: #c9d3cf;
--sl-color-gray-3: #95a39d;
--sl-color-gray-4: #5c6d66;
--sl-color-gray-5: #3a4844;
--sl-color-gray-6: #2a3531;
--sl-color-black: #1a201e;
}
/* Light mode tweaks so the green accent reads against white. */
:root[data-theme="light"] {
--sl-color-accent-low: #d0e4dc;
--sl-color-accent: #13715b;
--sl-color-accent-high: #0e5a48;
--sl-color-text-accent: #0e5a48;
}