Feature/docs

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Deploy Documentation
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build-and-deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build documentation
+        run: pnpm run docs:build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs-site/.vitepress/dist
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+

.gitignore

@@ -3,6 +3,8 @@ node_modules/
 
 # Build output
 dist/
+docs-site/.vitepress/dist/
+docs-site/.vitepress/cache/
 
 # Test output
 coverage/

docs-site/.vitepress/config.ts

@@ -0,0 +1,98 @@
+import { defineConfig } from 'vitepress';
+import { withMermaid } from 'vitepress-plugin-mermaid';
+
+export default withMermaid(
+  defineConfig({
+    title: 'itty-spec',
+    description: 'Contract-first, type-safe API definitions for itty-router',
+    base: '/itty-spec/',
+    lastUpdated: true,
+    ignoreDeadLinks: true,
+    cleanUrls: true,
+    markdown: {
+      theme: {
+        light: 'github-light',
+        dark: 'github-dark',
+      },
+    },
+    themeConfig: {
+      nav: [
+        { text: 'Guide', link: '/guide/getting-started' },
+        { text: 'API', link: '/api/' },
+        { text: 'Examples', link: '/examples/' },
+      ],
+      sidebar: {
+        '/guide/': [
+          {
+            text: 'Getting Started',
+            items: [
+              { text: 'Introduction', link: '/guide/getting-started' },
+              { text: 'Core Concepts', link: '/guide/core-concepts' },
+            ],
+          },
+          {
+            text: 'Guides',
+            items: [
+              { text: 'Contracts', link: '/guide/contracts' },
+              { text: 'Router Configuration', link: '/guide/router-configuration' },
+              { text: 'Validation', link: '/guide/validation' },
+              { text: 'Type Safety', link: '/guide/type-safety' },
+              { text: 'Content Types', link: '/guide/content-types' },
+              { text: 'Middleware', link: '/guide/middleware' },
+              { text: 'Error Handling', link: '/guide/error-handling' },
+              { text: 'OpenAPI Integration', link: '/guide/openapi' },
+              { text: 'Schema Libraries', link: '/guide/schema-libraries' },
+              { text: 'Best Practices', link: '/guide/best-practices' },
+              { text: 'Advanced Patterns', link: '/guide/advanced-patterns' },
+            ],
+          },
+          {
+            text: 'Additional',
+            items: [
+              { text: 'Migration Guide', link: '/guide/migration' },
+              { text: 'Troubleshooting', link: '/guide/troubleshooting' },
+              { text: 'FAQ', link: '/guide/faq' },
+            ],
+          },
+        ],
+        '/api/': [
+          {
+            text: 'API Reference',
+            items: [
+              { text: 'Overview', link: '/api/' },
+              { text: 'createContract', link: '/api/create-contract' },
+              { text: 'createRouter', link: '/api/create-router' },
+              { text: 'createOpenApiSpecification', link: '/api/create-openapi-specification' },
+              { text: 'Types', link: '/api/types' },
+              { text: 'Middleware API', link: '/api/middleware-api' },
+            ],
+          },
+        ],
+        '/examples/': [
+          {
+            text: 'Examples',
+            items: [
+              { text: 'Overview', link: '/examples/' },
+              { text: 'Simple Example', link: '/examples/simple' },
+              { text: 'Complex Example', link: '/examples/complex' },
+              { text: 'Valibot Example', link: '/examples/valibot' },
+              { text: 'Content Types', link: '/examples/content-types' },
+              { text: 'Authentication', link: '/examples/authentication' },
+              { text: 'File Upload', link: '/examples/file-upload' },
+            ],
+          },
+        ],
+      },
+      socialLinks: [
+        {
+          icon: 'github',
+          link: 'https://github.com/robertpitt/itty-spec',
+        },
+      ],
+      footer: {
+        message: 'Released under the MIT License.',
+        copyright: 'Copyright © 2024',
+      },
+    },
+  })
+);

docs-site/.vitepress/theme/index.ts

@@ -0,0 +1,8 @@
+// https://vitepress.dev/guide/custom-theme
+import type { Theme } from 'vitepress';
+import DefaultTheme from 'vitepress/theme';
+import './style.scss';
+
+export default {
+  extends: DefaultTheme,
+} satisfies Theme;