docs: set up astro starlight documentation infrastructure (#53)

* Initial plan

* docs: add astro starlight documentation site

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>

* docs: add astro starlight setup summary

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>

* docs: remove documentation content, keep only astro starlight setup

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>

* fix: pin github actions to sha hashes and fix indentation

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>

Author: Copilot

.github/workflows/deploy-docs.yml

@@ -0,0 +1,58 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs-site/**'
+      - '.github/workflows/deploy-docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: docs-site/package-lock.json
+
+      - name: Install dependencies
+        run: |
+          cd docs-site
+          npm ci
+
+      - name: Build documentation
+        run: |
+          cd docs-site
+          npm run build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
+        with:
+          path: docs-site/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4

.gitignore

@@ -11,3 +11,8 @@ coverage/
 *.swo
 *~
 .idea/
+
+# Documentation site build artifacts
+docs-site/dist/
+docs-site/.astro/
+docs-site/node_modules/

docs-site/README.md

@@ -0,0 +1,58 @@
+# Agentic Workflow Firewall Documentation
+
+This directory contains the Astro Starlight documentation site for the Agentic Workflow Firewall.
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+
+- npm
+
+### Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+```
+
+The site will be available at `http://localhost:4321`
+
+### Build
+
+```bash
+# Build for production
+npm run build
+
+# Preview production build
+npm run preview
+```
+
+## Structure
+
+```
+docs-site/
+├── src/
+│   ├── assets/          # Images and static assets
+│   ├── content/
+│   │   └── docs/        # Documentation content (Markdown/MDX)
+│   └── styles/          # Custom CSS
+├── public/              # Public static files
+├── astro.config.mjs     # Astro configuration
+└── package.json
+```
+
+## Deployment
+
+The documentation is automatically deployed to GitHub Pages when changes are pushed to the `main` branch.
+
+Workflow: `.github/workflows/deploy-docs.yml`
+
+## Links
+
+- [Astro Documentation](https://docs.astro.build/)
+- [Starlight Documentation](https://starlight.astro.build/)
+- [Live Site](https://githubnext.github.io/gh-aw-firewall/)

docs-site/astro.config.mjs

@@ -0,0 +1,27 @@
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+// https://astro.build/config
+export default defineConfig({
+	site: 'https://githubnext.github.io',
+	base: '/gh-aw-firewall',
+	integrations: [
+		starlight({
+			title: 'Agentic Workflow Firewall',
+			description: 'Network firewall for agentic workflows with domain whitelisting',
+			social: {
+				github: 'https://github.com/githubnext/gh-aw-firewall',
+			},
+			editLink: {
+				baseUrl: 'https://github.com/githubnext/gh-aw-firewall/edit/main/docs-site/',
+			},
+			logo: {
+				src: './src/assets/logo.svg',
+				replacesTitle: false,
+			},
+			customCss: [
+				'./src/styles/custom.css',
+			],
+		}),
+	],
+});