feat(docs-site): exhaustive Astro + refraction-ui documentation

.github/workflows/docs.yml

@@ -0,0 +1,83 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs-site/**'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'docs-site/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+# Cancel in-progress runs for the same ref so PR pushes don't pile up.
+concurrency:
+  group: docs-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  # --------------------------------------------------------------------------
+  # build — runs on every push to feat/* and every PR. A broken docs build
+  # must NOT sneak through into main. The job uploads the produced `dist/`
+  # as a Pages artifact so the deploy job can publish it on main.
+  # --------------------------------------------------------------------------
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    defaults:
+      run:
+        working-directory: docs-site
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: docs-site/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build static site
+        run: pnpm run build
+
+      - name: Verify pagefind index
+        run: |
+          test -f dist/pagefind/pagefind-entry.json \
+            || (echo "pagefind index missing" >&2; exit 1)
+
+      - name: Upload Pages artifact
+        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs-site/dist
+
+  # --------------------------------------------------------------------------
+  # deploy — only runs on pushes to main. Publishes the artifact uploaded by
+  # the build job to GitHub Pages. PR builds run the build job only.
+  # --------------------------------------------------------------------------
+  deploy:
+    name: Deploy to GitHub Pages
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -18,3 +18,8 @@ coverage*
 .DS_Store
 .idea/
 .vscode/
+
+# docs-site build artifacts
+docs-site/node_modules/
+docs-site/dist/
+docs-site/.astro/

README.md

@@ -155,6 +155,27 @@ check is bypassed. Never enable dev mode in production.
 | `NOTIFY_APNS_TOPIC` | string | — | Bundle id / topic. |
 | `NOTIFY_APNS_SANDBOX` | bool | `false` | Use the APNs sandbox endpoint. |
 
+## Docs
+
+Full documentation lives at [elloloop.github.io/notify](https://elloloop.github.io/notify/):
+
+- [Quick Start](https://elloloop.github.io/notify/docs/quickstart) — five-minute "hello, notify"
+- [Architecture](https://elloloop.github.io/notify/docs/concepts/architecture)
+- [Configuration reference](https://elloloop.github.io/notify/docs/installation/configuration)
+- [gRPC / Connect API](https://elloloop.github.io/notify/docs/api-reference/grpc)
+- [Send a notification](https://elloloop.github.io/notify/docs/examples/send-notification) — Go / Python / cURL
+- [Subscribe over SSE](https://elloloop.github.io/notify/docs/examples/subscribe-sse)
+
+The source is in [`docs-site/`](./docs-site) — an Astro static site
+built with the `@refraction-ui/astro` shell. Build it locally with:
+
+```bash
+cd docs-site
+pnpm install
+pnpm run build      # produces dist/
+pnpm run preview    # serves on http://127.0.0.1:4321/notify
+```
+
 ## License
 
 AGPL-3.0 — see [LICENSE](./LICENSE).

docs-site/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+.astro/
+dist/

docs-site/astro.config.mjs

@@ -0,0 +1,42 @@
+import { defineConfig } from "astro/config";
+import tailwind from "@astrojs/tailwind";
+import expressiveCode from "astro-expressive-code";
+import pagefind from "astro-pagefind";
+
+export default defineConfig({
+  site: "https://elloloop.github.io",
+  base: "/notify",
+  integrations: [
+    expressiveCode({
+      themes: ["github-dark-dimmed"],
+      styleOverrides: {
+        // Minimal, modern chrome — drop the macOS "traffic light" decoration.
+        frames: {
+          frameBoxShadowCssValue: "none",
+          editorTabBarBackground: "hsl(var(--muted))",
+          editorActiveTabIndicatorBottomColor: "hsl(var(--primary))",
+          editorActiveTabBorderColor: "transparent",
+          terminalTitlebarBackground: "hsl(var(--muted))",
+          terminalTitlebarBorderBottomColor: "hsl(var(--border))",
+          terminalBackground: "#22272e",
+          tooltipSuccessBackground: "hsl(var(--primary))",
+        },
+        borderRadius: "0.5rem",
+        codeFontFamily: "var(--font-mono)",
+        codeFontSize: "13px",
+        codeLineHeight: "1.65",
+        uiFontFamily: "var(--font-sans)",
+      },
+      defaultProps: {
+        // Hide the macOS-style window decoration buttons globally.
+        frame: "code",
+      },
+      shiki: {
+        // Match the prior Shiki configuration so language tags continue to work.
+      },
+    }),
+    tailwind({ applyBaseStyles: false }),
+    pagefind(),
+  ],
+  output: "static",
+});

docs-site/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "notify-docs",
+  "type": "module",
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview"
+  },
+  "dependencies": {
+    "@astrojs/tailwind": "5.1.5",
+    "@fontsource-variable/inter": "5.2.8",
+    "@fontsource-variable/jetbrains-mono": "5.2.8",
+    "@pagefind/default-ui": "1.5.2",
+    "@refraction-ui/astro": "0.4.11",
+    "@refraction-ui/tailwind-config": "0.1.6",
+    "astro": "5.18.1",
+    "astro-expressive-code": "0.41.7",
+    "astro-pagefind": "1.8.6",
+    "tailwindcss": "3.4.19"
+  }
+}