Skip to content

Commit cd69ded

Browse files
akshay5995akshay5995
committed
docs: add vitepress docs
1 parent 0c17541 commit cd69ded

File tree

12 files changed

+3349
-0
lines changed

12 files changed

+3349
-0
lines changed

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

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
name: Deploy docs
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths: ['docs/**']
7+
8+
# Allows you to run this workflow manually from the Actions tab
9+
workflow_dispatch:
10+
11+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
18+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
19+
concurrency:
20+
group: pages
21+
cancel-in-progress: false
22+
23+
jobs:
24+
# Build job
25+
build:
26+
runs-on: ubuntu-latest
27+
steps:
28+
- name: Checkout
29+
uses: actions/checkout@v4
30+
with:
31+
fetch-depth: 0 # Not needed if lastUpdated is not enabled
32+
- uses: pnpm/action-setup@v3
33+
with:
34+
version: 9
35+
- name: Setup Node
36+
uses: actions/setup-node@v4
37+
with:
38+
node-version: 22
39+
cache: pnpm
40+
- name: Setup Pages
41+
uses: actions/configure-pages@v4
42+
- name: Install dependencies
43+
run: pnpm install
44+
working-directory: docs
45+
- name: Build with VitePress
46+
run: pnpm run docs:build
47+
working-directory: docs
48+
- name: Upload artifact
49+
uses: actions/upload-pages-artifact@v3
50+
with:
51+
path: docs/.vitepress/dist
52+
53+
# Deployment job
54+
deploy:
55+
environment:
56+
name: github-pages
57+
url: ${{ steps.deployment.outputs.page_url }}
58+
needs: build
59+
runs-on: ubuntu-latest
60+
name: Deploy
61+
steps:
62+
- name: Deploy to GitHub Pages
63+
id: deployment
64+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -402,3 +402,10 @@ perf.data.old
402402

403403
# Docker compose
404404
!docker-compose.yml
405+
406+
# docs
407+
408+
!docs/*.yaml
409+
!docs/*.json
410+
411+
node_modules

‎docs/.vitepress/components/Mermaid.vue‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
<template>
2+
<div class="mermaid-container">
3+
<div v-if="showCode" class="mermaid-code">
4+
<details>
5+
<summary>Show Mermaid Code</summary>
6+
<pre><code>{{ decodedGraph }}</code></pre>
7+
</details>
8+
</div>
9+
<div :id="id" class="mermaid-diagram" v-html="renderedMermaid"></div>
10+
</div>
11+
</template>
12+
13+
<script setup lang="ts">
14+
import { ref, onMounted, computed, watch, nextTick } from 'vue'
15+
import { useData } from 'vitepress'
16+
import mermaid from 'mermaid'
17+
18+
const props = defineProps<{
19+
id: string
20+
graph: string
21+
showCode?: boolean
22+
}>()
23+
24+
const { isDark } = useData()
25+
const renderedMermaid = ref('')
26+
27+
const decodedGraph = computed(() => {
28+
try {
29+
return decodeURIComponent(props.graph)
30+
} catch {
31+
return props.graph
32+
}
33+
})
34+
35+
const getMermaidConfig = (isDarkMode: boolean) => ({
36+
startOnLoad: false,
37+
theme: isDarkMode ? 'dark' : 'default',
38+
securityLevel: 'loose',
39+
fontFamily: 'inherit',
40+
fontSize: 14,
41+
themeVariables: {
42+
// Ensure text is visible in both themes
43+
primaryColor: isDarkMode ? '#4f46e5' : '#3b82f6',
44+
primaryTextColor: isDarkMode ? '#f1f5f9' : '#1e293b',
45+
primaryBorderColor: isDarkMode ? '#6366f1' : '#2563eb',
46+
lineColor: isDarkMode ? '#64748b' : '#475569',
47+
sectionBkgColor: isDarkMode ? '#1e293b' : '#f8fafc',
48+
altSectionBkgColor: isDarkMode ? '#334155' : '#e2e8f0',
49+
gridColor: isDarkMode ? '#475569' : '#cbd5e1',
50+
secondaryColor: isDarkMode ? '#374151' : '#e5e7eb',
51+
tertiaryColor: isDarkMode ? '#4b5563' : '#d1d5db',
52+
background: isDarkMode ? '#0f172a' : '#ffffff',
53+
mainBkg: isDarkMode ? '#1e293b' : '#f8fafc',
54+
secondBkg: isDarkMode ? '#334155' : '#e2e8f0',
55+
},
56+
flowchart: {
57+
useMaxWidth: true,
58+
htmlLabels: true,
59+
curve: 'basis'
60+
},
61+
sequence: {
62+
useMaxWidth: true,
63+
wrap: true
64+
},
65+
gantt: {
66+
useMaxWidth: true
67+
}
68+
})
69+
70+
const renderDiagram = async () => {
71+
try {
72+
// Re-initialize mermaid with current theme
73+
mermaid.initialize(getMermaidConfig(isDark.value))
74+
75+
const graphDefinition = decodedGraph.value
76+
const uniqueId = `${props.id}_${isDark.value ? 'dark' : 'light'}_${Date.now()}`
77+
78+
// Render the mermaid diagram
79+
const { svg } = await mermaid.render(uniqueId, graphDefinition)
80+
renderedMermaid.value = svg
81+
} catch (error) {
82+
console.error('Failed to render Mermaid diagram:', error)
83+
renderedMermaid.value = `<div class="mermaid-error">
84+
<p><strong>Failed to render Mermaid diagram</strong></p>
85+
<pre>${decodedGraph.value}</pre>
86+
</div>`
87+
}
88+
}
89+
90+
// Watch for theme changes and re-render
91+
watch(isDark, () => {
92+
nextTick(() => {
93+
renderDiagram()
94+
})
95+
})
96+
97+
onMounted(() => {
98+
renderDiagram()
99+
})
100+
</script>
101+
102+
<style scoped>
103+
.mermaid-container {
104+
margin: 1rem 0;
105+
}
106+
107+
.mermaid-code {
108+
margin-bottom: 1rem;
109+
}
110+
111+
.mermaid-code details {
112+
border: 1px solid var(--vp-c-divider);
113+
border-radius: 6px;
114+
padding: 0.5rem;
115+
background: var(--vp-c-bg-alt);
116+
}
117+
118+
.mermaid-code summary {
119+
cursor: pointer;
120+
font-weight: 500;
121+
color: var(--vp-c-text-2);
122+
}
123+
124+
.mermaid-code pre {
125+
margin: 0.5rem 0 0 0;
126+
padding: 0;
127+
background: transparent;
128+
border: none;
129+
}
130+
131+
.mermaid-code code {
132+
font-family: var(--vp-font-family-mono);
133+
font-size: 0.875rem;
134+
color: var(--vp-c-text-1);
135+
}
136+
137+
.mermaid-diagram {
138+
text-align: center;
139+
background: var(--vp-c-bg);
140+
border-radius: 6px;
141+
padding: 1rem;
142+
border: 1px solid var(--vp-c-divider);
143+
}
144+
145+
.mermaid-diagram :deep(svg) {
146+
max-width: 100%;
147+
height: auto;
148+
}
149+
150+
.mermaid-error {
151+
color: var(--vp-c-danger-1);
152+
background: var(--vp-c-danger-soft);
153+
border: 1px solid var(--vp-c-danger-2);
154+
border-radius: 6px;
155+
padding: 1rem;
156+
}
157+
158+
.mermaid-error pre {
159+
background: transparent;
160+
color: var(--vp-c-text-1);
161+
font-size: 0.875rem;
162+
}
163+
</style>

‎docs/.vitepress/config.mts‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
import { defineConfig, MarkdownOptions } from 'vitepress'
2+
import MermaidExample from '../mermaid-markdown-all'
3+
4+
5+
const allMarkdownTransformers: MarkdownOptions = {
6+
config: (md) => {
7+
MermaidExample(md);
8+
},
9+
};
10+
11+
// https://vitepress.dev/reference/site-config
12+
export default defineConfig({
13+
title: 'MCP OAuth Gateway',
14+
description: 'OAuth 2.1 authorization server for Model Context Protocol (MCP) services',
15+
16+
head: [
17+
['link', { rel: 'icon', href: '/favicon.ico' }],
18+
['meta', { name: 'theme-color', content: '#3eaf7c' }],
19+
['meta', { name: 'apple-mobile-web-app-capable', content: 'yes' }],
20+
['meta', { name: 'apple-mobile-web-app-status-bar-style', content: 'black' }]
21+
],
22+
23+
themeConfig: {
24+
nav: [
25+
{ text: 'Quick Start', link: '/quick-start' },
26+
{ text: 'Architecture', link: '/architecture' },
27+
{
28+
text: 'Links',
29+
items: [
30+
{ text: 'GitHub', link: 'https://github.com/akshay5995/mcp-oauth-gateway' },
31+
{ text: 'Development Guide', link: 'https://github.com/akshay5995/mcp-oauth-gateway/blob/main/CLAUDE.md' },
32+
{ text: 'MCP Specification', link: 'https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization' }
33+
]
34+
}
35+
],
36+
37+
sidebar: [
38+
{ text: 'Quick Start', link: '/quick-start' },
39+
{ text: 'Architecture & Design', link: '/architecture' }
40+
],
41+
42+
socialLinks: [
43+
{ icon: 'github', link: 'https://github.com/akshay5995/mcp-oauth-gateway' }
44+
],
45+
46+
footer: {
47+
message: 'Released under the MIT License.',
48+
copyright: 'Copyright © 2025 MCP OAuth Gateway Contributors'
49+
},
50+
51+
search: {
52+
provider: 'local'
53+
},
54+
55+
editLink: {
56+
pattern: 'https://github.com/akshay5995/mcp-oauth-gateway/edit/main/docs/:path'
57+
},
58+
59+
lastUpdated: {
60+
text: 'Updated at',
61+
formatOptions: {
62+
dateStyle: 'full',
63+
timeStyle: 'medium'
64+
}
65+
}
66+
},
67+
68+
markdown: allMarkdownTransformers,
69+
})

‎docs/.vitepress/theme/custom.css‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
/* Custom styles for Mermaid diagrams */
2+
.mermaid-container {
3+
margin: 1.5rem 0;
4+
}
5+
6+
/* Dark theme support for Mermaid */
7+
html.dark .mermaid-diagram {
8+
background: var(--vp-c-bg-alt);
9+
}
10+
11+
/* Make Mermaid diagrams responsive */
12+
.mermaid-diagram svg {
13+
width: 100%;
14+
height: auto;
15+
display: block;
16+
}
17+
18+
/* Improve readability of Mermaid text in both themes */
19+
.mermaid-diagram .node rect,
20+
.mermaid-diagram .node circle,
21+
.mermaid-diagram .node ellipse,
22+
.mermaid-diagram .node polygon {
23+
stroke: var(--vp-c-border);
24+
fill: var(--vp-c-bg-soft);
25+
}
26+
27+
.mermaid-diagram .edgeLabel {
28+
background-color: var(--vp-c-bg);
29+
color: var(--vp-c-text-1);
30+
}
31+
32+
.mermaid-diagram .marker {
33+
fill: var(--vp-c-text-2);
34+
}
35+
36+
/* Sequence diagram improvements */
37+
.mermaid-diagram .actor {
38+
fill: var(--vp-c-bg-soft);
39+
stroke: var(--vp-c-border);
40+
}
41+
42+
.mermaid-diagram .messageLine0,
43+
.mermaid-diagram .messageLine1 {
44+
stroke: var(--vp-c-text-2);
45+
}

‎docs/.vitepress/theme/index.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
import DefaultTheme from 'vitepress/theme'
2+
import Mermaid from '../components/Mermaid.vue'
3+
import './custom.css'
4+
5+
export default {
6+
extends: DefaultTheme,
7+
enhanceApp({ app }) {
8+
app.component('Mermaid', Mermaid)
9+
}
10+
}

0 commit comments

Comments
 (0)