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

+16
View File
@@ -0,0 +1,16 @@
# Astro build
dist/
.astro/
# Dependencies
node_modules/
# Logs
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
# Env
.env
.env.production
+74
View File
@@ -0,0 +1,74 @@
import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";
import starlightOpenAPI, { openAPISidebarGroups } from "starlight-openapi";
// The OpenAPI spec lives in the server package. The Starlight integration
// reads it at build time and generates the full /api/reference/* tree.
const OPENAPI_PATH = "../../server/openapi.json";
export default defineConfig({
// Served at https://checkmate.so/docs — the leading slash is included so
// every internal link resolves correctly when fronted by a reverse proxy.
base: "/docs",
site: "https://checkmate.so",
integrations: [
starlight({
title: "Checkmate API",
description: "Use the Checkmate REST API to manage monitors, incidents, status pages, notifications, and users programmatically.",
// Prose markdown is loaded from /docs/api-content via the custom
// docsLoader in src/content.config.ts. Keeping content outside the
// Astro project tree means contributors can edit it without dealing
// with Astro / Starlight tooling.
logo: {
src: "./src/assets/logo.svg",
replacesTitle: true,
},
favicon: "/favicon.svg",
customCss: ["./src/styles/checkmate.css"],
social: {
github: "https://github.com/bluewave-labs/Checkmate",
},
sidebar: [
{
label: "Getting started",
items: [
{ label: "Introduction", slug: "introduction" },
{ label: "Quickstart", slug: "quickstart" },
{ label: "Authentication", slug: "authentication" },
],
},
{
label: "Core concepts",
items: [
{ label: "Conventions", slug: "conventions" },
{ label: "Errors", slug: "errors" },
{ label: "Rate limiting", slug: "rate-limiting" },
],
},
{
label: "API reference",
items: [
{ label: "Overview", slug: "api-reference/overview" },
// The OpenAPI plugin appends every endpoint under this group.
...openAPISidebarGroups,
],
},
],
plugins: [
starlightOpenAPI([
{
base: "api-reference",
label: "REST API",
schema: OPENAPI_PATH,
},
]),
],
}),
],
});
+20
View File
@@ -0,0 +1,20 @@
{
"name": "checkmate-docs-api",
"type": "module",
"version": "0.1.0",
"private": true,
"description": "Public API documentation for Checkmate. Built with Astro Starlight.",
"scripts": {
"dev": "astro dev",
"start": "astro dev",
"build": "astro build",
"preview": "astro preview",
"astro": "astro"
},
"dependencies": {
"@astrojs/starlight": "^0.30.0",
"astro": "^5.0.0",
"sharp": "^0.33.5",
"starlight-openapi": "^0.13.0"
}
}
+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;
}
+5
View File
@@ -0,0 +1,5 @@
{
"extends": "astro/tsconfigs/strict",
"include": [".astro/types.d.ts", "**/*"],
"exclude": ["dist"]
}
+7
View File
@@ -0,0 +1,7 @@
{
"$schema": "https://openapi.vercel.sh/vercel.json",
"buildCommand": "npm run build",
"outputDirectory": "dist",
"framework": "astro",
"installCommand": "npm install"
}