feat(website): docusaurus site published from /docs (#310)

Signed-off-by: robert-cronin <robert.owen.cronin@gmail.com>

Author: robert-cronin

.github/workflows/deploy-docs.yml

@@ -0,0 +1,76 @@
+name: Deploy Docs Website
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'website/**'
+      - 'docs/**'
+      - '.github/workflows/deploy-docs.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'website/**'
+      - 'docs/**'
+      - '.github/workflows/deploy-docs.yml'
+
+permissions:
+  contents: read
+
+# Allow one concurrent deployment in flight; don't cancel in-progress deploys
+# from earlier main pushes (those are real publishes we want to complete).
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build website
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    defaults:
+      run:
+        working-directory: website
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: 1.3.11
+
+      - name: Install dependencies
+        run: bun ci
+
+      - name: Build website
+        run: bun run build
+
+      - name: Upload Pages artifact
+        # GitHub Pages needs the artifact uploaded under the specific name
+        # "github-pages" so deploy-pages picks it up.
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: website/build
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    # Only publish on push to main on the canonical repo. PR builds verify the
+    # build but never deploy. Permissions scoped to this job alone so PR
+    # builds keep a read-only token.
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push' && github.repository == 'kaito-project/airunway'
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

README.md

@@ -100,6 +100,10 @@ The controller automatically selects the best engine and provider, creates provi
 
 ## Documentation
 
+📖 **Browse the docs at [kaito-project.github.io/airunway](https://kaito-project.github.io/airunway/)**
+
+The same content also lives in [`docs/`](docs/) for in-repo browsing.
+
 | Topic | Link |
 | --- | --- |
 | Architecture | [docs/architecture.md](docs/architecture.md) |

agents.md

@@ -20,7 +20,8 @@
 - `backend/src/` - Hono app, providers, services
 - `shared/types/` - Shared TypeScript definitions
 - `plugins/headlamp/` - Headlamp dashboard plugin
-- `docs/` - Detailed documentation (read as needed)
+- `docs/` - Detailed documentation (read as needed; also the source rendered on the website)
+- `website/` - Docusaurus site published to https://kaito-project.github.io/airunway/. Reads from `docs/` via `docs.path: '../docs'` — write docs as plain GitHub-Flavored Markdown and they render in both places.
 
 **Core pattern**: Provider abstraction via CRDs:
 - `ModelDeployment` - Unified API for deploying ML models
@@ -71,6 +72,22 @@ make setup               # Install deps, build, and deploy to Headlamp
 make dev                 # Build and deploy for development
 ```
 
+### Website (Docusaurus)
+
+```bash
+cd website
+bun install              # Install website dependencies
+bun run start            # Local dev server with hot reload
+bun run build            # Production build (must pass before merge)
+bun run serve            # Serve the production build locally
+```
+
+Docs sources stay in `/docs/*.md` (single source of truth). When the build
+warns about a broken link or MDX issue, fix the source markdown — the site is
+configured with `markdown.format: 'detect'` so `.md` files are treated as
+plain GFM, not MDX. Anything in `{curly braces}` or bare `<angle-tags>` in a
+`.md` file will only be parsed as JSX if the file is renamed to `.mdx`.
+
 **Always run `bun run test` after implementing functionality to verify both frontend and backend changes.**
 
 **Always validate changes immediately after editing files:**

docs/api.md

@@ -1474,7 +1474,7 @@ Check if AI Configurator CLI is available on the system.
 **Notes:**
 
 - Status is cached for 5 minutes to avoid repeated CLI calls
-- AI Configurator must be installed locally: <https://github.com/ai-dynamo/aiconfigurator>
+- AI Configurator must be installed locally: [github.com/ai-dynamo/aiconfigurator](https://github.com/ai-dynamo/aiconfigurator)
 - When running inside Kubernetes, returns `runningInCluster: true` (AI Configurator is local-only)
 
 ### POST /aiconfigurator/analyze

docs/gateway.md

@@ -1,6 +1,6 @@
 # Gateway API Inference Extension Integration
 
-> **Pinned versions:** the `GAIE_VERSION` referenced in this document is sourced from [`/versions.env`](../versions.env) at the repo root. Substitute that value (currently `v1.5.0`) when running the commands below, or `source` the file in your shell: `set -a; source versions.env; set +a`.
+> **Pinned versions:** the `GAIE_VERSION` referenced in this document is sourced from [`/versions.env`](https://github.com/kaito-project/airunway/blob/main/versions.env) at the repo root. Substitute that value (currently `v1.5.0`) when running the commands below, or `source` the file in your shell: `set -a; source versions.env; set +a`.
 
 ## Overview
 
@@ -81,7 +81,7 @@ AI Runway works with any Gateway API implementation that supports the [Inference
 > (Step 3), the `inference-gateway` Gateway resource (Step 4), and the Body-Based Router (see
 > [Body-Based Routing](#body-based-routing-bbr)). The
 > `GATEWAY_API_VERSION`, `ISTIO_VERSION`, and `GAIE_VERSION` it uses are pinned in
-> [`/versions.env`](../versions.env), and `istioctl` must be on your PATH. For other gateway
+> [`/versions.env`](https://github.com/kaito-project/airunway/blob/main/versions.env), and `istioctl` must be on your PATH. For other gateway
 > implementations, follow the manual steps below.
 
 ### Step 1: Install Gateway API CRDs
@@ -206,7 +206,7 @@ helm install body-based-router \
 ```
 
 > [!NOTE]
-> The BBR chart version should match the GAIE version used by AI Runway. The pinned value lives in [`/versions.env`](../versions.env); update both at the same time when bumping.
+> The BBR chart version should match the GAIE version used by AI Runway. The pinned value lives in [`/versions.env`](https://github.com/kaito-project/airunway/blob/main/versions.env); update both at the same time when bumping.
 
 Replace `provider.name` with your gateway implementation (`istio`, `gke`, or omit for others). The chart deploys the BBR container and any provider-specific resources (e.g. EnvoyFilter for Istio).
 

docs/headlamp-plugin.md

@@ -2,7 +2,7 @@
 
 This document describes the architecture, design decisions, and technical details of the AI Runway Headlamp plugin.
 
-For installation and development instructions, see the [plugin README](../plugins/headlamp/README.md).
+For installation and development instructions, see the [plugin README](https://github.com/kaito-project/airunway/blob/main/plugins/headlamp/README.md).
 
 ---
 

docs/observability.md

@@ -15,7 +15,7 @@ AI Runway exposes Prometheus metrics from both the controller and inference prov
 
 ## Getting started
 
-See the [Observability Demo](../demos/observability/README.md) for a complete walkthrough covering:
+See the [Observability Demo](https://github.com/kaito-project/airunway/blob/main/demos/observability/README.md) for a complete walkthrough covering:
 
 1. Installing kube-prometheus-stack
 2. Configuring Prometheus to scrape the controller (ServiceMonitor + RBAC)

docs/providers.md

@@ -79,10 +79,10 @@ The Web UI backend reads provider information (capabilities, installation steps,
 
 | Provider      | Upstream CRD          | Status      | Shim YAML | Description                                                                    |
 | ------------- | --------------------- | ----------- | --------- | ------------------------------------------------------------------------------ |
-| NVIDIA Dynamo | DynamoGraphDeployment | ✅ Available | [dynamo.yaml](../providers/dynamo/deploy/dynamo.yaml) | High-performance GPU inference with KV-cache routing and disaggregated serving |
-| KubeRay       | RayService            | ✅ Available | [kuberay.yaml](../providers/kuberay/deploy/kuberay.yaml) | Ray-based distributed inference with autoscaling                               |
-| KAITO         | Workspace             | ✅ Available | [kaito.yaml](../providers/kaito/deploy/kaito.yaml) | Flexible inference with vLLM (GPU) or llama.cpp (CPU/GPU)                      |
-| llm-d         | none                  | ✅ Available | [llmd.yaml](../providers/llmd/deploy/llmd.yaml) | Flexible inference with vLLM (GPU) with KV-cache routing and disaggregated serving |
+| NVIDIA Dynamo | DynamoGraphDeployment | ✅ Available | [dynamo.yaml](https://github.com/kaito-project/airunway/blob/main/providers/dynamo/deploy/dynamo.yaml) | High-performance GPU inference with KV-cache routing and disaggregated serving |
+| KubeRay       | RayService            | ✅ Available | [kuberay.yaml](https://github.com/kaito-project/airunway/blob/main/providers/kuberay/deploy/kuberay.yaml) | Ray-based distributed inference with autoscaling                               |
+| KAITO         | Workspace             | ✅ Available | [kaito.yaml](https://github.com/kaito-project/airunway/blob/main/providers/kaito/deploy/kaito.yaml) | Flexible inference with vLLM (GPU) or llama.cpp (CPU/GPU)                      |
+| llm-d         | none                  | ✅ Available | [llmd.yaml](https://github.com/kaito-project/airunway/blob/main/providers/llmd/deploy/llmd.yaml) | Flexible inference with vLLM (GPU) with KV-cache routing and disaggregated serving |
 
 ### KAITO Provider
 

website/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

website/README.md

@@ -0,0 +1,44 @@
+# AI Runway website
+
+This is the source for the AI Runway documentation site published at
+[**kaito-project.github.io/airunway**](https://kaito-project.github.io/airunway/).
+Built with [Docusaurus](https://docusaurus.io/) 3.
+
+## Content layout
+
+The site renders content from two places:
+
+- `/website/src/pages/` — landing page and other React pages
+- `/docs/*.md` (at the repo root) — every documentation page
+
+The docs plugin is configured with `docs.path: '../docs'` so the markdown
+files double as in-repo docs (viewable on GitHub) and as the website's
+content. **Write docs as plain GitHub-Flavored Markdown.** Docusaurus is set
+to `markdown.format: 'detect'`, which means `.md` files are NOT treated as
+MDX — content like `{name}` or `<pod-name>` renders verbatim. If you want
+JSX, rename the file to `.mdx`.
+
+When you add a new doc, also add it to [`sidebars.js`](./sidebars.js).
+
+## Local development
+
+Requires [Bun](https://bun.sh/) (matches the rest of the repo).
+
+```bash
+bun install      # one-time
+bun run start    # http://localhost:3000/airunway/ with hot reload
+bun run build    # what CI runs; must pass before merge
+bun run serve    # serve the production build locally on :3000
+```
+
+## Deployment
+
+`.github/workflows/deploy-docs.yml` builds the site and publishes it via the
+GitHub Actions Pages flow (`actions/upload-pages-artifact` →
+`actions/deploy-pages`). The site is deployed on every push to `main` on the
+canonical `kaito-project/airunway` repo. Pull requests and forks build the
+site to verify it compiles, but only the canonical repo deploys.
+
+First-time setup (needs a repository admin): **Settings → Pages → Build and
+deployment → Source = "GitHub Actions"**. No `gh-pages` branch is involved —
+the artifact is served directly from the workflow.