docs: add vitepress docs

.github/workflows/deploy-docs.yml

@@ -0,0 +1,64 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+    paths: ['docs/**']
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Not needed if lastUpdated is not enabled
+      - uses: pnpm/action-setup@v3
+        with:
+          version: 9
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Install dependencies
+        run: pnpm install
+        working-directory: docs
+      - name: Build with VitePress
+        run: pnpm run docs:build
+        working-directory: docs
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    name: Deploy
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -402,3 +402,10 @@ perf.data.old
 
 # Docker compose
 !docker-compose.yml
+
+# docs
+
+!docs/*.yaml
+!docs/*.json
+
+node_modules

docs/.vitepress/components/Mermaid.vue

@@ -0,0 +1,163 @@
+<template>
+  <div class="mermaid-container">
+    <div v-if="showCode" class="mermaid-code">
+      <details>
+        <summary>Show Mermaid Code</summary>
+        <pre><code>{{ decodedGraph }}</code></pre>
+      </details>
+    </div>
+    <div :id="id" class="mermaid-diagram" v-html="renderedMermaid"></div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted, computed, watch, nextTick } from 'vue'
+import { useData } from 'vitepress'
+import mermaid from 'mermaid'
+
+const props = defineProps<{
+  id: string
+  graph: string
+  showCode?: boolean
+}>()
+
+const { isDark } = useData()
+const renderedMermaid = ref('')
+
+const decodedGraph = computed(() => {
+  try {
+    return decodeURIComponent(props.graph)
+  } catch {
+    return props.graph
+  }
+})
+
+const getMermaidConfig = (isDarkMode: boolean) => ({
+  startOnLoad: false,
+  theme: isDarkMode ? 'dark' : 'default',
+  securityLevel: 'loose',
+  fontFamily: 'inherit',
+  fontSize: 14,
+  themeVariables: {
+    // Ensure text is visible in both themes
+    primaryColor: isDarkMode ? '#4f46e5' : '#3b82f6',
+    primaryTextColor: isDarkMode ? '#f1f5f9' : '#1e293b',
+    primaryBorderColor: isDarkMode ? '#6366f1' : '#2563eb',
+    lineColor: isDarkMode ? '#64748b' : '#475569',
+    sectionBkgColor: isDarkMode ? '#1e293b' : '#f8fafc',
+    altSectionBkgColor: isDarkMode ? '#334155' : '#e2e8f0',
+    gridColor: isDarkMode ? '#475569' : '#cbd5e1',
+    secondaryColor: isDarkMode ? '#374151' : '#e5e7eb',
+    tertiaryColor: isDarkMode ? '#4b5563' : '#d1d5db',
+    background: isDarkMode ? '#0f172a' : '#ffffff',
+    mainBkg: isDarkMode ? '#1e293b' : '#f8fafc',
+    secondBkg: isDarkMode ? '#334155' : '#e2e8f0',
+  },
+  flowchart: {
+    useMaxWidth: true,
+    htmlLabels: true,
+    curve: 'basis'
+  },
+  sequence: {
+    useMaxWidth: true,
+    wrap: true
+  },
+  gantt: {
+    useMaxWidth: true
+  }
+})
+
+const renderDiagram = async () => {
+  try {
+    // Re-initialize mermaid with current theme
+    mermaid.initialize(getMermaidConfig(isDark.value))
+
+    const graphDefinition = decodedGraph.value
+    const uniqueId = `${props.id}_${isDark.value ? 'dark' : 'light'}_${Date.now()}`
+
+    // Render the mermaid diagram
+    const { svg } = await mermaid.render(uniqueId, graphDefinition)
+    renderedMermaid.value = svg
+  } catch (error) {
+    console.error('Failed to render Mermaid diagram:', error)
+    renderedMermaid.value = `<div class="mermaid-error">
+      <p><strong>Failed to render Mermaid diagram</strong></p>
+      <pre>${decodedGraph.value}</pre>
+    </div>`
+  }
+}
+
+// Watch for theme changes and re-render
+watch(isDark, () => {
+  nextTick(() => {
+    renderDiagram()
+  })
+})
+
+onMounted(() => {
+  renderDiagram()
+})
+</script>
+
+<style scoped>
+.mermaid-container {
+  margin: 1rem 0;
+}
+
+.mermaid-code {
+  margin-bottom: 1rem;
+}
+
+.mermaid-code details {
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 6px;
+  padding: 0.5rem;
+  background: var(--vp-c-bg-alt);
+}
+
+.mermaid-code summary {
+  cursor: pointer;
+  font-weight: 500;
+  color: var(--vp-c-text-2);
+}
+
+.mermaid-code pre {
+  margin: 0.5rem 0 0 0;
+  padding: 0;
+  background: transparent;
+  border: none;
+}
+
+.mermaid-code code {
+  font-family: var(--vp-font-family-mono);
+  font-size: 0.875rem;
+  color: var(--vp-c-text-1);
+}
+
+.mermaid-diagram {
+  text-align: center;
+  background: var(--vp-c-bg);
+  border-radius: 6px;
+  padding: 1rem;
+  border: 1px solid var(--vp-c-divider);
+}
+
+.mermaid-diagram :deep(svg) {
+  max-width: 100%;
+  height: auto;
+}
+
+.mermaid-error {
+  color: var(--vp-c-danger-1);
+  background: var(--vp-c-danger-soft);
+  border: 1px solid var(--vp-c-danger-2);
+  border-radius: 6px;
+  padding: 1rem;
+}
+
+.mermaid-error pre {
+  background: transparent;
+  color: var(--vp-c-text-1);
+  font-size: 0.875rem;
+}
+</style>

docs/.vitepress/config.mts

@@ -0,0 +1,69 @@
+import { defineConfig, MarkdownOptions } from 'vitepress'
+import MermaidExample from '../mermaid-markdown-all'
+
+
+const allMarkdownTransformers: MarkdownOptions = {
+  config: (md) => {
+    MermaidExample(md);
+  },
+};
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: 'MCP OAuth Gateway',
+  description: 'OAuth 2.1 authorization server for Model Context Protocol (MCP) services',
+
+  head: [
+    ['link', { rel: 'icon', href: '/favicon.ico' }],
+    ['meta', { name: 'theme-color', content: '#3eaf7c' }],
+    ['meta', { name: 'apple-mobile-web-app-capable', content: 'yes' }],
+    ['meta', { name: 'apple-mobile-web-app-status-bar-style', content: 'black' }]
+  ],
+
+  themeConfig: {
+    nav: [
+      { text: 'Quick Start', link: '/quick-start' },
+      { text: 'Architecture', link: '/architecture' },
+      { 
+        text: 'Links',
+        items: [
+          { text: 'GitHub', link: 'https://github.com/akshay5995/mcp-oauth-gateway' },
+          { text: 'Development Guide', link: 'https://github.com/akshay5995/mcp-oauth-gateway/blob/main/CLAUDE.md' },
+          { text: 'MCP Specification', link: 'https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization' }
+        ]
+      }
+    ],
+
+    sidebar: [
+      { text: 'Quick Start', link: '/quick-start' },
+      { text: 'Architecture & Design', link: '/architecture' }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/akshay5995/mcp-oauth-gateway' }
+    ],
+
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright © 2025 MCP OAuth Gateway Contributors'
+    },
+
+    search: {
+      provider: 'local'
+    },
+
+    editLink: {
+      pattern: 'https://github.com/akshay5995/mcp-oauth-gateway/edit/main/docs/:path'
+    },
+
+    lastUpdated: {
+      text: 'Updated at',
+      formatOptions: {
+        dateStyle: 'full',
+        timeStyle: 'medium'
+      }
+    }
+  },
+
+  markdown: allMarkdownTransformers,
+})

docs/.vitepress/theme/custom.css

@@ -0,0 +1,45 @@
+/* Custom styles for Mermaid diagrams */
+.mermaid-container {
+  margin: 1.5rem 0;
+}
+
+/* Dark theme support for Mermaid */
+html.dark .mermaid-diagram {
+  background: var(--vp-c-bg-alt);
+}
+
+/* Make Mermaid diagrams responsive */
+.mermaid-diagram svg {
+  width: 100%;
+  height: auto;
+  display: block;
+}
+
+/* Improve readability of Mermaid text in both themes */
+.mermaid-diagram .node rect,
+.mermaid-diagram .node circle,
+.mermaid-diagram .node ellipse,
+.mermaid-diagram .node polygon {
+  stroke: var(--vp-c-border);
+  fill: var(--vp-c-bg-soft);
+}
+
+.mermaid-diagram .edgeLabel {
+  background-color: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+}
+
+.mermaid-diagram .marker {
+  fill: var(--vp-c-text-2);
+}
+
+/* Sequence diagram improvements */
+.mermaid-diagram .actor {
+  fill: var(--vp-c-bg-soft);
+  stroke: var(--vp-c-border);
+}
+
+.mermaid-diagram .messageLine0,
+.mermaid-diagram .messageLine1 {
+  stroke: var(--vp-c-text-2);
+}

docs/.vitepress/theme/index.ts

@@ -0,0 +1,10 @@
+import DefaultTheme from 'vitepress/theme'
+import Mermaid from '../components/Mermaid.vue'
+import './custom.css'
+
+export default {
+  extends: DefaultTheme,
+  enhanceApp({ app }) {
+    app.component('Mermaid', Mermaid)
+  }
+}