Skip to content

Commit 6cba032

Browse files
ChristianPavilonisChristianPavilonis
authored
Vitepress docs site (#143)
* basic docs site setup with some ai docs * add integration guide to vitepress site. * more docs * adds config reference * docs: add GitHub Pages setup guide and enable workflow on feature branch - Add comprehensive README.md with GitHub Pages setup instructions - Update deploy-docs.yml to run on feature/docs-site branch for testing - Document custom domain configuration process - Include DNS setup and verification steps * set basepath * docs: add quick wins reference documentation Add four high-impact quick reference guides: - Integrations Overview: Comparison table of all built-in integrations (Prebid, Next.js, Permutive, Testlight) with features, endpoints, configuration examples, and use cases - API Reference: Complete endpoint catalog with request/response formats, query parameters, authentication, examples for all first-party, signing, TSJS, and integration endpoints - Environment Variables: Comprehensive guide to configuration via env vars including naming patterns, data type formats, secrets management, and complete examples for all integrations and settings - Error Reference: Common errors, causes, and solutions organized by category (configuration, runtime, integrations, signing, build/deploy) with debugging tips and troubleshooting steps Add new Reference section to sidebar with these guides for easy access
1 parent 614c9bc commit 6cba032

28 files changed

+9667
-0
lines changed

‎.github/workflows/deploy-docs.yml‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
name: Deploy VitePress Docs
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- 'docs/**'
8+
- '.github/workflows/deploy-docs.yml'
9+
workflow_dispatch: # Allow manual triggers
10+
11+
# Sets permissions for GitHub Pages deployment
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
# Prevent concurrent deployments
18+
concurrency:
19+
group: pages
20+
cancel-in-progress: false
21+
22+
jobs:
23+
build:
24+
runs-on: ubuntu-latest
25+
steps:
26+
- name: Checkout
27+
uses: actions/checkout@v4
28+
with:
29+
fetch-depth: 0 # For lastUpdated feature
30+
31+
- name: Retrieve Node.js version
32+
id: node-version
33+
run: echo "node-version=$(grep '^nodejs ' .tool-versions | awk '{print $2}')" >> $GITHUB_OUTPUT
34+
35+
- name: Setup Node.js
36+
uses: actions/setup-node@v4
37+
with:
38+
node-version: ${{ steps.node-version.outputs.node-version }}
39+
cache: 'npm'
40+
cache-dependency-path: docs/package-lock.json
41+
42+
- name: Setup Pages
43+
uses: actions/configure-pages@v4
44+
45+
- name: Install dependencies
46+
working-directory: docs
47+
run: npm ci
48+
49+
- name: Build with VitePress
50+
working-directory: docs
51+
run: npm run build
52+
53+
- name: Upload artifact
54+
uses: actions/upload-pages-artifact@v3
55+
with:
56+
path: docs/.vitepress/dist
57+
58+
deploy:
59+
environment:
60+
name: github-pages
61+
url: ${{ steps.deployment.outputs.page_url }}
62+
needs: build
63+
runs-on: ubuntu-latest
64+
steps:
65+
- name: Deploy to GitHub Pages
66+
id: deployment
67+
uses: actions/deploy-pages@v4

‎docs/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
node_modules
2+
.vitepress/dist
3+
.vitepress/cache

‎docs/.vitepress/config.mts‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
import { defineConfig } from 'vitepress'
2+
3+
// https://vitepress.dev/reference/site-config
4+
export default defineConfig({
5+
title: "Trusted Server",
6+
description: "Privacy-preserving edge computing for ad serving and synthetic ID generation",
7+
base: "/trusted-server",
8+
themeConfig: {
9+
// https://vitepress.dev/reference/default-theme-config
10+
nav: [
11+
{ text: 'Home', link: '/' },
12+
{ text: 'Guide', link: '/guide/getting-started' },
13+
],
14+
15+
sidebar: [
16+
{
17+
text: 'Introduction',
18+
items: [
19+
{ text: 'What is Trusted Server?', link: '/guide/what-is-trusted-server' },
20+
{ text: 'Getting Started', link: '/guide/getting-started' }
21+
]
22+
},
23+
{
24+
text: 'Core Concepts',
25+
items: [
26+
{ text: 'Synthetic IDs', link: '/guide/synthetic-ids' },
27+
{ text: 'GDPR Compliance', link: '/guide/gdpr-compliance' },
28+
{ text: 'Ad Serving', link: '/guide/ad-serving' },
29+
{ text: 'First-Party Proxy', link: '/guide/first-party-proxy' },
30+
{ text: 'Creative Processing', link: '/guide/creative-processing' },
31+
{ text: 'Integrations Overview', link: '/guide/integrations-overview' }
32+
]
33+
},
34+
{
35+
text: 'Security',
36+
items: [
37+
{ text: 'Request Signing', link: '/guide/request-signing' },
38+
{ text: 'Key Rotation', link: '/guide/key-rotation' }
39+
]
40+
},
41+
{
42+
text: 'Development',
43+
items: [
44+
{ text: 'Architecture', link: '/guide/architecture' },
45+
{ text: 'Configuration', link: '/guide/configuration' },
46+
{ text: 'Configuration Reference', link: '/guide/configuration-reference' },
47+
{ text: 'Testing', link: '/guide/testing' },
48+
{ text: 'Integration Guide', link: '/guide/integration-guide' }
49+
]
50+
},
51+
{
52+
text: 'Reference',
53+
items: [
54+
{ text: 'API Reference', link: '/guide/api-reference' },
55+
{ text: 'Environment Variables', link: '/guide/environment-variables' },
56+
{ text: 'Error Reference', link: '/guide/error-reference' }
57+
]
58+
}
59+
],
60+
61+
socialLinks: [
62+
{ icon: 'github', link: 'https://github.com/IABTechLab/trusted-server' }
63+
],
64+
65+
footer: {
66+
message: 'Released under the Apache License 2.0.',
67+
copyright: 'Copyright © 2018-present IAB Technology Laboratory'
68+
}
69+
}
70+
})

‎docs/README.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# Trusted Server Documentation
2+
3+
VitePress documentation site for Trusted Server.
4+
5+
## Local Development
6+
7+
### Prerequisites
8+
9+
- Node.js 24.10.0 (or version specified in `.tool-versions`)
10+
- npm
11+
12+
### Setup
13+
14+
```bash
15+
# Install dependencies
16+
npm install
17+
18+
# Start dev server (available at localhost:5173)
19+
npm run dev
20+
```
21+
22+
### Build
23+
24+
```bash
25+
# Build for production
26+
npm run build
27+
28+
# Preview production build
29+
npm run preview
30+
```
31+
32+
## GitHub Pages Deployment
33+
34+
The documentation is automatically deployed to GitHub Pages when changes are pushed to the `main` branch.
35+
36+
### Setup GitHub Pages
37+
38+
1. Go to repository **Settings** → **Pages**
39+
2. Under **Source**, select **GitHub Actions**
40+
3. The workflow in `.github/workflows/deploy-docs.yml` will automatically deploy on push to `main`
41+
42+
### Custom Domain Setup
43+
44+
1. **Update CNAME file**: Edit `docs/public/CNAME` with your domain:
45+
```
46+
docs.yourdomain.com
47+
```
48+
49+
2. **Configure DNS**: Add DNS records at your domain provider:
50+
51+
**Option A - CNAME Record** (recommended for subdomains):
52+
```
53+
Type: CNAME
54+
Name: docs
55+
Value: iabtechlab.github.io
56+
```
57+
58+
**Option B - A Records** (for apex domains):
59+
```
60+
Type: A
61+
Name: @
62+
Value: 185.199.108.153
63+
Value: 185.199.109.153
64+
Value: 185.199.110.153
65+
Value: 185.199.111.153
66+
```
67+
68+
3. **Verify in GitHub**:
69+
- Go to **Settings** → **Pages**
70+
- Enter your custom domain
71+
- Wait for DNS check to pass
72+
- Enable "Enforce HTTPS"
73+
74+
### Workflow Details
75+
76+
**Trigger**:
77+
- Push to `main` branch (only when `docs/**` changes)
78+
- Manual trigger via Actions tab
79+
80+
**Build Process**:
81+
1. Checkout repository with full history (for `lastUpdated` feature)
82+
2. Setup Node.js (version from `.tool-versions`)
83+
3. Install dependencies (`npm ci`)
84+
4. Build VitePress site (`npm run build`)
85+
5. Upload build artifact
86+
6. Deploy to GitHub Pages
87+
88+
**Permissions Required**:
89+
- `contents: read` - Read repository
90+
- `pages: write` - Deploy to Pages
91+
- `id-token: write` - OIDC token for deployment
92+
93+
## Troubleshooting
94+
95+
### Build Fails in GitHub Actions
96+
97+
**Check**:
98+
- Node.js version matches `.tool-versions`
99+
- All dependencies in `package.json` are correct
100+
- Build succeeds locally (`npm run build`)
101+
102+
**View Logs**:
103+
1. Go to **Actions** tab in GitHub
104+
2. Click on failed workflow run
105+
3. Review build logs
106+
107+
### Custom Domain Not Working
108+
109+
**Check**:
110+
- DNS records propagated (use `dig docs.yourdomain.com`)
111+
- CNAME file exists in `docs/public/CNAME`
112+
- Custom domain verified in GitHub Pages settings
113+
- HTTPS enforced (may take up to 24 hours)
114+
115+
**DNS Verification**:
116+
```bash
117+
# Check CNAME record
118+
dig docs.yourdomain.com CNAME
119+
120+
# Check A records (for apex domain)
121+
dig yourdomain.com A
122+
```
123+
124+
### 404 Errors
125+
126+
**Check**:
127+
- VitePress `base` config (should not be set for custom domains)
128+
- Links use correct paths (start with `/`)
129+
- Build output in `docs/.vitepress/dist` is correct
130+
131+
## Project Structure
132+
133+
```
134+
docs/
135+
├── .vitepress/
136+
│ ├── config.mts # VitePress configuration
137+
│ └── dist/ # Build output (gitignored)
138+
├── guide/ # Documentation pages
139+
│ ├── getting-started.md
140+
│ ├── configuration.md
141+
│ └── ...
142+
├── public/ # Static assets
143+
│ └── CNAME # Custom domain file
144+
├── index.md # Homepage
145+
├── package.json # Dependencies
146+
└── README.md # This file
147+
```
148+
149+
## Contributing
150+
151+
When adding new documentation:
152+
153+
1. Create `.md` files in `docs/guide/`
154+
2. Update sidebar in `docs/.vitepress/config.mts`
155+
3. Test locally with `npm run dev`
156+
4. Build and verify with `npm run build && npm run preview`
157+
5. Commit and push to trigger deployment
158+
159+
## Links
160+
161+
- **Production**: (Configure your custom domain)
162+
- **GitHub Repo**: https://github.com/IABTechLab/trusted-server
163+
- **VitePress Docs**: https://vitepress.dev

0 commit comments

Comments
 (0)