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:
1 parent
9027707c92
commit
9aa2594df7
16 files changed
+991
No files matched your search
@@ -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
|
||||
@@ -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,
|
||||
},
|
||||
]),
|
||||
],
|
||||
}),
|
||||
],
|
||||
});
|
||||
@@ -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"
|
||||
}
|
||||
}
|
||||
@@ -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 |
@@ -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(),
|
||||
}),
|
||||
};
|
||||
@@ -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;
|
||||
}
|
||||
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"extends": "astro/tsconfigs/strict",
|
||||
"include": [".astro/types.d.ts", "**/*"],
|
||||
"exclude": ["dist"]
|
||||
}
|
||||
@@ -0,0 +1,7 @@
|
||||
{
|
||||
"$schema": "https://openapi.vercel.sh/vercel.json",
|
||||
"buildCommand": "npm run build",
|
||||
"outputDirectory": "dist",
|
||||
"framework": "astro",
|
||||
"installCommand": "npm install"
|
||||
}
|
||||
Reference in new issue
Block a user