docs: deploy stable and beta docs

.github/workflows/docs.yaml

@@ -0,0 +1,81 @@
+name: Docs
+on:
+  push:
+    tags:
+      - "v*"
+    branches:
+      - "release/docs"
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  beta:
+    name: Deploy Beta Docs
+    if: startsWith(github.ref, 'refs/tags/v') && contains(github.ref_name, '-')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v6
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          run_install: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: package.json
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build docs
+        run: pnpm docs:build
+        env:
+          HEADPLANE_BETA_DOCS: "true"
+
+      - name: Deploy to Cloudflare Pages
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CF_API_TOKEN }}
+          command: pages deploy docs/.vitepress/dist --project-name=headplane-docs-beta
+
+  stable:
+    name: Deploy Stable Docs
+    if: >
+      (startsWith(github.ref, 'refs/tags/v') && !contains(github.ref_name, '-'))
+      || github.ref == 'refs/heads/release/docs'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v6
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          run_install: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: package.json
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build docs
+        run: pnpm docs:build
+
+      - name: Deploy to Cloudflare Pages
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CF_API_TOKEN }}
+          command: pages deploy docs/.vitepress/dist --project-name=headplane-docs

.npmrc

@@ -1 +1,2 @@
 side-effects-cache = false
+public-hoist-pattern[]=vue

docs/.vitepress/config.ts

@@ -1,6 +1,11 @@
 import { defineConfig } from "vitepress";
 
 export default defineConfig({
+  vite: {
+    define: {
+      __HEADPLANE_BETA_DOCS__: JSON.stringify(process.env.HEADPLANE_BETA_DOCS === "true"),
+    },
+  },
   title: "Headplane",
   description: "The missing dashboard for Headscale",
   cleanUrls: true,

docs/.vitepress/theme/custom.css

@@ -1,17 +1,42 @@
 html.dark .light-only {
-	display: none !important;
+  display: none !important;
 }
 
 html:not(.dark) .dark-only {
-	display: none !important;
+  display: none !important;
 }
 
 figure {
-	padding: 1em;
+  padding: 1em;
 }
 
 figcaption {
-	text-align: center;
-	font-size: 0.9em;
-	margin-top: 0.5em;
+  text-align: center;
+  font-size: 0.9em;
+  margin-top: 0.5em;
+}
+
+:root {
+  --vp-layout-top-height: 36px;
+}
+
+.beta-banner {
+  background-color: var(--vp-c-bg);
+  background-image: linear-gradient(var(--vp-c-warning-soft), var(--vp-c-warning-soft));
+  color: var(--vp-c-warning-1);
+  text-align: center;
+  padding: 8px 16px;
+  font-size: 14px;
+  font-weight: 500;
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  z-index: 100;
+}
+
+.beta-banner a {
+  color: var(--vp-c-warning-1);
+  text-decoration: underline;
+  margin-left: 8px;
 }

docs/.vitepress/theme/env.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="vitepress/client" />
+
+declare const __HEADPLANE_BETA_DOCS__: boolean;

docs/.vitepress/theme/index.ts

@@ -1,4 +1,36 @@
-import DefaultTheme from 'vitepress/theme';
-import './custom.css';
+import type { Theme } from "vitepress";
+import DefaultTheme from "vitepress/theme";
+import { h } from "vue";
 
-export default DefaultTheme;
+import "./custom.css";
+
+const beta = __HEADPLANE_BETA_DOCS__ ?? false;
+
+export default {
+  extends: DefaultTheme,
+  Layout() {
+    return h(DefaultTheme.Layout, null, {
+      "layout-top": () =>
+        beta
+          ? h(
+              "div",
+              {
+                class: "beta-banner",
+              },
+              [
+                "You are currently viewing the ",
+                h("strong", "beta"),
+                " documentation for Headplane. ",
+                h(
+                  "a",
+                  {
+                    href: "https://headplane.net",
+                  },
+                  "Go to the stable docs →",
+                ),
+              ],
+            )
+          : null,
+    });
+  },
+} satisfies Theme;

docs/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "include": [".vitepress/**/*"],
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "target": "ES2022",
+    "lib": ["DOM", "DOM.Iterable", "ES2023"],
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true
+  }
+}

tsconfig.json

@@ -1,5 +1,6 @@
 {
   "include": ["**/*", "**/.server/**/*", "**/.client/**/*", ".react-router/types/**/*"],
+  "exclude": ["docs"],
   "compilerOptions": {
     "lib": ["DOM", "DOM.Iterable", "ES2023"],
     "types": ["node", "vite/client"],

wrangler.toml

@@ -1,6 +0,0 @@
-name = "headplane"
-compatibility_date = "2025-08-18"
-
-[assets]
-directory = "docs/.vitepress/dist"
-not_found_handling = "404-page"