docs(site): add GitHub Pages publishing with MkDocs

Author: acmore

.github/workflows/docs.yml

@@ -0,0 +1,52 @@
+name: Docs
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install MkDocs
+        run: pip install mkdocs mkdocs-material
+
+      - name: Build docs site
+        run: mkdocs build --strict
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -13,3 +13,11 @@ See:
 - `docs/command-reference.md`
 - `docs/okdev-design.md`
 - `docs/okdev-implementation-plan.md`
+
+## GitHub Pages Docs
+
+Docs are published from `docs/` via GitHub Actions + MkDocs.
+
+- Workflow: `.github/workflows/docs.yml`
+- Source config: `mkdocs.yml`
+- Expected URL: `https://acmore.github.io/okdev/`

docs/index.md

@@ -0,0 +1,19 @@
+# okdev
+
+Lightweight Kubernetes-native dev environments for AI infra engineering.
+
+## What You Get
+
+- PodSpec-first config via `.okdev.yaml`
+- Multi-session support per repo/branch/user
+- Shell/SSH access, sync, and port forwarding
+- Cross-machine reattach with cluster-native session identity
+- Optional Syncthing sync engine
+
+## Read the Docs
+
+- [Quickstart](quickstart.md)
+- [Command Reference](command-reference.md)
+- [Design](okdev-design.md)
+- [Implementation Plan](okdev-implementation-plan.md)
+- [Troubleshooting](troubleshooting.md)

mkdocs.yml

@@ -0,0 +1,22 @@
+site_name: okdev
+site_description: Lightweight Kubernetes-native dev environments for AI infra engineering
+repo_url: https://github.com/acmore/okdev
+repo_name: acmore/okdev
+theme:
+  name: material
+  features:
+    - navigation.sections
+    - navigation.expand
+    - content.code.copy
+markdown_extensions:
+  - admonition
+  - tables
+  - toc:
+      permalink: true
+nav:
+  - Home: index.md
+  - Quickstart: quickstart.md
+  - Command Reference: command-reference.md
+  - Design: okdev-design.md
+  - Implementation Plan: okdev-implementation-plan.md
+  - Troubleshooting: troubleshooting.md