docs: start the developer docs site with self-hosting and the API

.github/pull_request_template.md

@@ -0,0 +1,10 @@
+## Before
+
+## After
+
+## How
+
+## Checks
+
+- [ ] `bun run check`, `bun run lint`, `bun run format:check` and `bun run build` pass
+- [ ] Pages describe what the linked release does, not what's planned

.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+# Pushes to other branches are covered by their pull request, so running on
+# both would check every commit twice.
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  site:
+    name: Lint, check and build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: package.json
+      - run: bun install --frozen-lockfile
+      - run: bun run lint
+      - run: bun run format:check
+      - run: bun run check
+      - run: bun run build

.gitignore

@@ -0,0 +1,22 @@
+node_modules/
+dist/
+.astro/
+out/
+coverage/
+*.tsbuildinfo
+*.log
+.env
+.env.*
+!.env.example
+.DS_Store
+
+# Share editor settings even when .vscode is globally ignored.
+!.vscode/
+.vscode/*
+!.vscode/settings.json
+!.vscode/extensions.json
+
+# Cloudflare deployment artifacts
+.cloudflare/
+
+.agents/

.oxfmtrc.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "semi": false,
+  "ignorePatterns": ["AGENTS.md", "bun.lock", "**/dist/**", "**/.astro/**", "src/content/**"]
+}

.oxlintrc.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "categories": {
+    "correctness": "error"
+  },
+  "ignorePatterns": ["**/node_modules/**", "**/dist/**", "**/out/**", "**/coverage/**"]
+}

AGENTS.md

@@ -0,0 +1,55 @@
+# AGENTS.md
+
+Guidance for anyone changing this repository, human or agent. Read it before writing.
+
+## What this is
+
+The public developer documentation for Chek, served at docs.chek.page. It's for people who self-host Chek server, build on its API, write source extensions, or embed Chek Reader. Product direction lives in [readchek/chek's docs/product.md](https://github.com/readchek/chek/blob/main/docs/product.md); the marketing site is [readchek/chek.page](https://github.com/readchek/chek.page).
+
+## Decisions already made
+
+- **Astro Starlight**, built with Bun and deployed to Cloudflare as static files, like chek.page. Pages are Markdown or MDX in `src/content/docs`. Starlight ships no client framework; if a page ever needs an interactive component, write it in SolidJS through `@astrojs/solid-js`, never React or Vue.
+- **Sources of truth stay in their repositories.** The API reference is built by `starlight-openapi` from `openapi.yaml` at the chek release named by `chekRelease` in `astro.config.ts`. Don't copy the spec here. Raise `chekRelease` when the guides have caught up with a new release.
+- **Describe what's released.** Pages describe what the release in `chekRelease` does, not what's planned or only on `main`.
+- **Public only.** Nothing here names private infrastructure, private repositories or anyone's credentials. Design decisions and internal deploys stay in their own repositories' `docs/`.
+- **Brand.** Colors and fonts come from chek.page's tokens, set as Starlight variables in `src/styles/brand.css`. Fonts are served from the site, so the page never calls another origin.
+
+## Layout
+
+| Path | Contents |
+| --- | --- |
+| `src/content/docs/get-started` | What Chek is and the quick start |
+| `src/content/docs/self-hosting` | Installing, configuring and running Chek server |
+| `src/content/docs/api` | API guides. The reference under `/api/reference` is generated |
+| `astro.config.ts` | Site config, sidebar and the pinned chek release |
+| `scripts/cloudflare.ts` | Turns the static build into Cloudflare's prebuilt output |
+
+## Build
+
+```sh
+bun install
+bun run dev          # http://localhost:4321
+bun run lint && bun run format:check && bun run check && bun run build
+```
+
+The build fetches `openapi.yaml` from GitHub, so it needs network. `bun run deploy` builds and publishes to Cloudflare, after `cf auth login`.
+
+## Writing
+
+Pages follow the pstack `technical-writing` and `unslop` skills.
+
+- Give each page one mode. The quick start is a tutorial. Task pages are how-to guides, titled by the task, such as "Serve Chek over HTTPS". Configuration and the API overview are reference. "What Chek is" is explanation.
+- Talk to the reader as "you", in the present tense, with one instruction or one thought per sentence. Split sentences longer than about 25 words.
+- Put the condition before the instruction: "To pin a release, set `CHEK_IMAGE`."
+- No em dashes, semicolons, slashes, or idioms. Never "simply", "easy", or "quickly".
+- Use the real name of every variable, endpoint, error code, and file. Call each thing by one name on every page.
+- Check every setting, endpoint, and default against the code or `openapi.yaml` at `chekRelease` before you write it down.
+- Indent code with tabs, except YAML.
+- Every page has a `description` in its front matter. Search and link previews use it.
+- Link between pages with root-relative paths that end in `/`, such as `/self-hosting/install/`.
+
+## Pull requests
+
+- Branch from `main`, keep each PR to one change, and merge by squash.
+- Fill in the PR template with "Before", "After" and "How" in plain language.
+- When a change in chek, chek-reader or app alters something these pages describe, open a PR here too.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

README.md

@@ -1,3 +1,22 @@
-# Chek Docs
+<p align="center">
+  <img src="https://raw.githubusercontent.com/readchek/chek.page/main/public/assets/logos/mark.svg" alt="Chek" width="80" height="80" />
+</p>
 
-Developer documentation for Chek, served at [docs.chek.page](https://docs.chek.page).
+<h1 align="center">Chek Docs</h1>
+
+<p align="center">Developer documentation for Chek, at <a href="https://docs.chek.page">docs.chek.page</a>.</p>
+
+Guides for running your own Chek server, building on its API, writing source extensions and embedding Chek Reader, with the API reference built from the server's `openapi.yaml`.
+
+## Run it
+
+```sh
+bun install
+bun run dev        # http://localhost:4321
+```
+
+Before a pull request, run `bun run lint`, `bun run format:check`, `bun run check` and `bun run build`; CI runs them too. [AGENTS.md](AGENTS.md) covers how the site is built and how to write for it.
+
+## Deploy
+
+`bun run deploy` builds the site and publishes it to Cloudflare at docs.chek.page, after `cf auth login`.

astro.config.ts

@@ -0,0 +1,61 @@
+import starlight from "@astrojs/starlight"
+import { defineConfig } from "astro/config"
+import starlightOpenAPI, { openAPISidebarGroups } from "starlight-openapi"
+
+// The server release these pages describe. The API reference is built from
+// that release's openapi.yaml, so raise this when the guides catch up with a
+// new release, not before.
+const chekRelease = "0.3.0"
+
+export default defineConfig({
+  site: "https://docs.chek.page",
+  integrations: [
+    starlight({
+      title: "Chek Docs",
+      description:
+        "Run your own Chek server, build on its API, write source extensions and embed Chek Reader.",
+      logo: { src: "./src/assets/mark.svg", alt: "Chek" },
+      favicon: "/favicon.svg",
+      customCss: ["./src/styles/brand.css"],
+      social: [{ icon: "github", label: "GitHub", href: "https://github.com/readchek" }],
+      editLink: { baseUrl: "https://github.com/readchek/docs/edit/main/" },
+      plugins: [
+        starlightOpenAPI([
+          {
+            base: "api/reference",
+            schema: `https://raw.githubusercontent.com/readchek/chek/${chekRelease}/openapi.yaml`,
+            sidebar: { label: "Reference", operations: { badges: true } },
+          },
+        ]),
+      ],
+      sidebar: [
+        {
+          label: "Get started",
+          items: ["get-started/introduction", "get-started/quick-start"],
+        },
+        {
+          label: "Self-hosting",
+          items: [
+            "self-hosting/install",
+            "self-hosting/first-steps",
+            "self-hosting/configuration",
+            "self-hosting/reverse-proxy",
+            "self-hosting/users",
+            "self-hosting/sign-in-providers",
+            "self-hosting/komga-and-kavita",
+            "self-hosting/opds",
+            "self-hosting/uploads",
+            "self-hosting/extensions",
+            "self-hosting/updating-and-backups",
+            "self-hosting/logs",
+            "self-hosting/troubleshooting",
+          ],
+        },
+        {
+          label: "API",
+          items: ["api/overview", "api/reading", ...openAPISidebarGroups],
+        },
+      ],
+    }),
+  ],
+})