Vitepress docs site

.github/workflows/deploy-docs.yml

@@ -0,0 +1,67 @@
+name: Deploy VitePress Docs
+
+on:
+  push:
+    branches: [main, feature/docs-site]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/deploy-docs.yml'
+  workflow_dispatch:  # Allow manual triggers
+
+# Sets permissions for GitHub Pages deployment
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Prevent concurrent deployments
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # For lastUpdated feature
+
+      - name: Retrieve Node.js version
+        id: node-version
+        run: echo "node-version=$(grep '^nodejs ' .tool-versions | awk '{print $2}')" >> $GITHUB_OUTPUT
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ steps.node-version.outputs.node-version }}
+          cache: 'npm'
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Install dependencies
+        working-directory: docs
+        run: npm ci
+
+      - name: Build with VitePress
+        working-directory: docs
+        run: npm run build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+.vitepress/dist
+.vitepress/cache

docs/.vitepress/config.mts

@@ -0,0 +1,60 @@
+import { defineConfig } from 'vitepress'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "Trusted Server",
+  description: "Privacy-preserving edge computing for ad serving and synthetic ID generation",
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Guide', link: '/guide/getting-started' },
+    ],
+
+    sidebar: [
+      {
+        text: 'Introduction',
+        items: [
+          { text: 'What is Trusted Server?', link: '/guide/what-is-trusted-server' },
+          { text: 'Getting Started', link: '/guide/getting-started' }
+        ]
+      },
+      {
+        text: 'Core Concepts',
+        items: [
+          { text: 'Synthetic IDs', link: '/guide/synthetic-ids' },
+          { text: 'GDPR Compliance', link: '/guide/gdpr-compliance' },
+          { text: 'Ad Serving', link: '/guide/ad-serving' },
+          { text: 'First-Party Proxy', link: '/guide/first-party-proxy' },
+          { text: 'Creative Processing', link: '/guide/creative-processing' }
+        ]
+      },
+      {
+        text: 'Security',
+        items: [
+          { text: 'Request Signing', link: '/guide/request-signing' },
+          { text: 'Key Rotation', link: '/guide/key-rotation' }
+        ]
+      },
+      {
+        text: 'Development',
+        items: [
+          { text: 'Architecture', link: '/guide/architecture' },
+          { text: 'Configuration', link: '/guide/configuration' },
+          { text: 'Configuration Reference', link: '/guide/configuration-reference' },
+          { text: 'Testing', link: '/guide/testing' },
+          { text: 'Integration Guide', link: '/guide/integration-guide' }
+        ]
+      }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/IABTechLab/trusted-server' }
+    ],
+
+    footer: {
+      message: 'Released under the Apache License 2.0.',
+      copyright: 'Copyright © 2018-present IAB Technology Laboratory'
+    }
+  }
+})

docs/README.md

@@ -0,0 +1,163 @@
+# Trusted Server Documentation
+
+VitePress documentation site for Trusted Server.
+
+## Local Development
+
+### Prerequisites
+
+- Node.js 24.10.0 (or version specified in `.tool-versions`)
+- npm
+
+### Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Start dev server (available at localhost:5173)
+npm run dev
+```
+
+### Build
+
+```bash
+# Build for production
+npm run build
+
+# Preview production build
+npm run preview
+```
+
+## GitHub Pages Deployment
+
+The documentation is automatically deployed to GitHub Pages when changes are pushed to the `main` branch.
+
+### Setup GitHub Pages
+
+1. Go to repository **Settings** → **Pages**
+2. Under **Source**, select **GitHub Actions**
+3. The workflow in `.github/workflows/deploy-docs.yml` will automatically deploy on push to `main`
+
+### Custom Domain Setup
+
+1. **Update CNAME file**: Edit `docs/public/CNAME` with your domain:
+   ```
+   docs.yourdomain.com
+   ```
+
+2. **Configure DNS**: Add DNS records at your domain provider:
+
+   **Option A - CNAME Record** (recommended for subdomains):
+   ```
+   Type: CNAME
+   Name: docs
+   Value: iabtechlab.github.io
+   ```
+
+   **Option B - A Records** (for apex domains):
+   ```
+   Type: A
+   Name: @
+   Value: 185.199.108.153
+   Value: 185.199.109.153
+   Value: 185.199.110.153
+   Value: 185.199.111.153
+   ```
+
+3. **Verify in GitHub**:
+   - Go to **Settings** → **Pages**
+   - Enter your custom domain
+   - Wait for DNS check to pass
+   - Enable "Enforce HTTPS"
+
+### Workflow Details
+
+**Trigger**: 
+- Push to `main` branch (only when `docs/**` changes)
+- Manual trigger via Actions tab
+
+**Build Process**:
+1. Checkout repository with full history (for `lastUpdated` feature)
+2. Setup Node.js (version from `.tool-versions`)
+3. Install dependencies (`npm ci`)
+4. Build VitePress site (`npm run build`)
+5. Upload build artifact
+6. Deploy to GitHub Pages
+
+**Permissions Required**:
+- `contents: read` - Read repository
+- `pages: write` - Deploy to Pages
+- `id-token: write` - OIDC token for deployment
+
+## Troubleshooting
+
+### Build Fails in GitHub Actions
+
+**Check**:
+- Node.js version matches `.tool-versions`
+- All dependencies in `package.json` are correct
+- Build succeeds locally (`npm run build`)
+
+**View Logs**:
+1. Go to **Actions** tab in GitHub
+2. Click on failed workflow run
+3. Review build logs
+
+### Custom Domain Not Working
+
+**Check**:
+- DNS records propagated (use `dig docs.yourdomain.com`)
+- CNAME file exists in `docs/public/CNAME`
+- Custom domain verified in GitHub Pages settings
+- HTTPS enforced (may take up to 24 hours)
+
+**DNS Verification**:
+```bash
+# Check CNAME record
+dig docs.yourdomain.com CNAME
+
+# Check A records (for apex domain)
+dig yourdomain.com A
+```
+
+### 404 Errors
+
+**Check**:
+- VitePress `base` config (should not be set for custom domains)
+- Links use correct paths (start with `/`)
+- Build output in `docs/.vitepress/dist` is correct
+
+## Project Structure
+
+```
+docs/
+├── .vitepress/
+│   ├── config.mts          # VitePress configuration
+│   └── dist/               # Build output (gitignored)
+├── guide/                  # Documentation pages
+│   ├── getting-started.md
+│   ├── configuration.md
+│   └── ...
+├── public/                 # Static assets
+│   └── CNAME              # Custom domain file
+├── index.md               # Homepage
+├── package.json           # Dependencies
+└── README.md             # This file
+```
+
+## Contributing
+
+When adding new documentation:
+
+1. Create `.md` files in `docs/guide/`
+2. Update sidebar in `docs/.vitepress/config.mts`
+3. Test locally with `npm run dev`
+4. Build and verify with `npm run build && npm run preview`
+5. Commit and push to trigger deployment
+
+## Links
+
+- **Production**: (Configure your custom domain)
+- **GitHub Repo**: https://github.com/IABTechLab/trusted-server
+- **VitePress Docs**: https://vitepress.dev