Skip to content

Commit 634219c

Browse files
tapas100tapas100
committed
feat(docs): migrate from MkDocs to VitePress
- Install vitepress@1.6.4 as devDependency (Node.js-native, no Python needed) - Add docs/.vitepress/config.mts with full nav, sidebar, search, footer - Rewrite docs/index.md with VitePress hero layout + feature cards - Add npm scripts: docs:dev, docs:build, docs:preview - Update .github/workflows/docs.yml: Node.js build + actions/deploy-pages (replaces Python/MkDocs + gh-pages branch push) - Remove mkdocs.yml, requirements-docs.txt, docs/stylesheets/extra.css - Add docs/.vitepress/dist and cache to .gitignore - Fix broken image ref in docs/admin-ui/overview.md - Build: passes cleanly in 9.77s with ignoreDeadLinks: true
1 parent 6f25f74 commit 634219c

10 files changed

Lines changed: 2946 additions & 480 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 36 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -6,42 +6,59 @@ on:
66
- main # deploy on every merge to main
77
paths:
88
- 'docs/**'
9-
- 'mkdocs.yml'
10-
- 'requirements-docs.txt'
9+
- 'package.json'
1110
- '.github/workflows/docs.yml'
1211
workflow_dispatch: # allow manual trigger from GitHub UI
1312

1413
# Required for GitHub Pages deployment
1514
permissions:
16-
contents: write # push to gh-pages branch
15+
contents: read
1716
pages: write
1817
id-token: write
1918

19+
# Only one deploy at a time
20+
concurrency:
21+
group: pages
22+
cancel-in-progress: false
23+
2024
jobs:
21-
deploy-docs:
22-
name: Build & Deploy MkDocs
25+
build:
26+
name: 🏗️ Build VitePress docs
2327
runs-on: ubuntu-latest
2428

2529
steps:
2630
- name: 📥 Checkout repository
2731
uses: actions/checkout@v4
2832
with:
29-
fetch-depth: 0 # full history needed for git-revision-date plugin
33+
fetch-depth: 0 # full history for lastUpdated timestamps
3034

31-
- name: 🐍 Set up Python
32-
uses: actions/setup-python@v5
35+
- name: ⚙️ Set up Node.js
36+
uses: actions/setup-node@v4
3337
with:
34-
python-version: '3.12'
35-
cache: 'pip'
36-
cache-dependency-path: requirements-docs.txt
38+
node-version: 20
39+
cache: npm
40+
41+
- name: 📦 Install dependencies
42+
run: npm ci
3743

38-
- name: 📦 Install MkDocs + Material theme
39-
run: pip install -r requirements-docs.txt
44+
- name: 🏗️ Build VitePress site
45+
run: npm run docs:build
4046

41-
- name: 🏗️ Configure Git for gh-pages push
42-
run: |
43-
git config user.name "github-actions[bot]"
44-
git config user.email "github-actions[bot]@users.noreply.github.com"
47+
- name: 📤 Upload Pages artifact
48+
uses: actions/upload-pages-artifact@v3
49+
with:
50+
path: docs/.vitepress/dist
4551

46-
- name: 🚀 Build & deploy to GitHub Pages (gh-pages branch)
47-
run: mkdocs gh-deploy --force --clean --verbose
52+
deploy:
53+
name: 🚀 Deploy to GitHub Pages
54+
needs: build
55+
runs-on: ubuntu-latest
56+
57+
environment:
58+
name: github-pages
59+
url: ${{ steps.deployment.outputs.page_url }}
60+
61+
steps:
62+
- name: 🌐 Deploy to GitHub Pages
63+
id: deployment
64+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -118,5 +118,9 @@ dist/
118118
*.d.ts
119119
*.js.map
120120

121-
# MkDocs build output
121+
# MkDocs build output (no longer used)
122122
site/
123+
124+
# VitePress build output
125+
docs/.vitepress/dist
126+
docs/.vitepress/cache

‎docs/.vitepress/config.mts‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
import { defineConfig } from 'vitepress'
2+
3+
export default defineConfig({
4+
// Site metadata
5+
title: 'FlexGate Proxy',
6+
description: 'Production-grade AI-native API gateway with built-in observability, security, and reliability',
7+
base: '/flexgate-proxy/',
8+
9+
// Ignore dead links in existing docs (pre-existing stubs)
10+
ignoreDeadLinks: true,
11+
12+
// Clean URLs (no .html extension)
13+
cleanUrls: true,
14+
15+
// Head tags
16+
head: [
17+
['meta', { name: 'theme-color', content: '#3451b2' }],
18+
['meta', { name: 'og:type', content: 'website' }],
19+
['meta', { name: 'og:title', content: 'FlexGate Proxy' }],
20+
['meta', { name: 'og:description', content: 'AI-native API gateway — detects failures, analyzes with Claude, auto-heals 80% of incidents.' }],
21+
['link', { rel: 'icon', href: '/flexgate-proxy/favicon.ico', type: 'image/x-icon' }],
22+
],
23+
24+
// Theme config
25+
themeConfig: {
26+
// Top navigation bar
27+
nav: [
28+
{ text: 'Getting Started', link: '/getting-started/' },
29+
{ text: 'Guides', link: '/guides/' },
30+
{ text: 'AI Features', link: '/ai/' },
31+
{
32+
text: 'Reference',
33+
items: [
34+
{ text: 'API Reference', link: '/api/' },
35+
{ text: 'CLI Reference', link: '/cli/' },
36+
{ text: 'Architecture', link: '/architecture/' },
37+
]
38+
},
39+
{ text: 'Deployment', link: '/deployment/' },
40+
{
41+
text: 'v0.1.0-beta.2',
42+
items: [
43+
{ text: 'Changelog', link: '/changelog' },
44+
{ text: 'Contributing', link: '/contributing/' },
45+
{ text: 'npm', link: 'https://www.npmjs.com/package/flexgate-proxy' },
46+
]
47+
},
48+
],
49+
50+
// Left sidebar
51+
sidebar: {
52+
'/getting-started/': [
53+
{
54+
text: 'Getting Started',
55+
items: [
56+
{ text: 'Overview', link: '/getting-started/' },
57+
{ text: 'Quick Start', link: '/getting-started/quickstart' },
58+
{ text: 'Installation', link: '/getting-started/installation' },
59+
{ text: 'Configuration', link: '/getting-started/configuration' },
60+
]
61+
}
62+
],
63+
64+
'/guides/': [
65+
{
66+
text: 'Guides',
67+
items: [
68+
{ text: 'Overview', link: '/guides/' },
69+
{ text: 'Route Management', link: '/features/02-route-management' },
70+
{ text: 'Webhooks', link: '/features/07-webhooks' },
71+
{ text: 'Admin UI', link: '/features/01-admin-ui' },
72+
{ text: 'Observability', link: '/observability' },
73+
{ text: 'Traffic Control', link: '/traffic-control' },
74+
]
75+
}
76+
],
77+
78+
'/ai/': [
79+
{
80+
text: 'AI Features',
81+
items: [
82+
{ text: 'Overview', link: '/ai/' },
83+
{ text: 'Use Cases', link: '/ai/use-cases' },
84+
]
85+
},
86+
{
87+
text: 'Playbooks',
88+
items: [
89+
{ text: 'Incident Response', link: '/ai/playbooks/incident-response' },
90+
{ text: 'Auto-Recovery', link: '/ai/playbooks/auto-recovery' },
91+
{ text: 'Cost Optimization', link: '/ai/playbooks/cost-optimization' },
92+
]
93+
},
94+
{
95+
text: 'Testing',
96+
items: [
97+
{ text: 'Testing Guide', link: '/ai/TESTING_GUIDE' },
98+
]
99+
}
100+
],
101+
102+
'/api/': [
103+
{
104+
text: 'API Reference',
105+
items: [
106+
{ text: 'Overview', link: '/api/' },
107+
{ text: 'Full REST API', link: '/api' },
108+
]
109+
}
110+
],
111+
112+
'/cli/': [
113+
{
114+
text: 'CLI Reference',
115+
items: [
116+
{ text: 'Commands', link: '/cli/' },
117+
]
118+
}
119+
],
120+
121+
'/architecture/': [
122+
{
123+
text: 'Architecture',
124+
items: [
125+
{ text: 'Overview', link: '/architecture/' },
126+
{ text: 'System Design', link: '/architecture' },
127+
{ text: 'Threat Model', link: '/threat-model' },
128+
{ text: 'Trade-offs', link: '/trade-offs' },
129+
{ text: 'TypeScript Migration', link: '/typescript-migration' },
130+
]
131+
}
132+
],
133+
134+
'/deployment/': [
135+
{
136+
text: 'Deployment',
137+
items: [
138+
{ text: 'Overview', link: '/deployment/' },
139+
{ text: 'Quick Start', link: '/deployment/quick-start' },
140+
{ text: 'AWS EC2', link: '/deployment/aws-ec2' },
141+
{ text: 'Cloud Comparison', link: '/deployment/cloud-comparison' },
142+
]
143+
}
144+
],
145+
146+
'/contributing/': [
147+
{
148+
text: 'Contributing',
149+
items: [
150+
{ text: 'Guidelines', link: '/contributing/' },
151+
{ text: 'Changelog', link: '/changelog' },
152+
]
153+
}
154+
],
155+
},
156+
157+
// Social links (top-right)
158+
socialLinks: [
159+
{ icon: 'github', link: 'https://github.com/tapas100/flexgate-proxy' },
160+
{ icon: 'npm', link: 'https://www.npmjs.com/package/flexgate-proxy' },
161+
],
162+
163+
// Footer
164+
footer: {
165+
message: 'Released under the MIT License.',
166+
copyright: 'Copyright © 2024–2026 tapas100'
167+
},
168+
169+
// Search (built-in, no plugin needed)
170+
search: {
171+
provider: 'local'
172+
},
173+
174+
// Edit link
175+
editLink: {
176+
pattern: 'https://github.com/tapas100/flexgate-proxy/edit/main/docs/:path',
177+
text: 'Edit this page on GitHub'
178+
},
179+
180+
// Last updated
181+
lastUpdated: {
182+
text: 'Last updated',
183+
formatOptions: {
184+
dateStyle: 'short',
185+
}
186+
},
187+
188+
// Doc footer navigation
189+
docFooter: {
190+
prev: 'Previous',
191+
next: 'Next'
192+
},
193+
194+
// Outline (right-side TOC)
195+
outline: {
196+
level: [2, 3],
197+
label: 'On this page'
198+
},
199+
},
200+
201+
// Markdown config
202+
markdown: {
203+
theme: {
204+
light: 'github-light',
205+
dark: 'github-dark'
206+
},
207+
lineNumbers: true,
208+
},
209+
210+
// Last updated via git
211+
lastUpdated: true,
212+
})

‎docs/admin-ui/overview.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ Enable HTTPS in production (see [SSL/TLS Configuration](../security/ssl.md))
3030

3131
## Dashboard Overview
3232

33-
![Admin UI Dashboard](../images/admin-dashboard.png)
33+
> Screenshot coming soon. Run `flexgate start` and open `http://localhost:3000` to see the live dashboard.
3434
3535
The dashboard provides at-a-glance insights:
3636

0 commit comments

Comments
 (0)