From 1db13156ab4407d765107eeeb2f2db9d61f48a86 Mon Sep 17 00:00:00 2001 From: Govind Kamtamneni Date: Thu, 12 Feb 2026 17:30:48 -0800 Subject: [PATCH 1/4] feat(deep-wiki): add /deep-wiki:deploy command for GitHub Pages deployment - New commands/deploy.md: generates .github/workflows/deploy-wiki.yml - Workflow builds VitePress wiki and deploys to GitHub Pages - Auto-detects base path (project vs user/org site) - Triggers on push to main (wiki/** paths) + manual dispatch - Instructs user to enable Pages via Actions in repo settings - Updated README, docs-site, and root README with new command --- .github/plugins/deep-wiki/README.md | 7 + .github/plugins/deep-wiki/commands/deploy.md | 178 +++++++++++++++++++ README.md | 2 +- docs-site/src/pages/index.astro | 4 + 4 files changed, 190 insertions(+), 1 deletion(-) create mode 100644 .github/plugins/deep-wiki/commands/deploy.md diff --git a/.github/plugins/deep-wiki/README.md b/.github/plugins/deep-wiki/README.md index 6aa1b31..e7d1329 100644 --- a/.github/plugins/deep-wiki/README.md +++ b/.github/plugins/deep-wiki/README.md @@ -33,6 +33,7 @@ copilot --plugin-dir ./deep-wiki | `/deep-wiki:llms` | Generate `llms.txt` and `llms-full.txt` for LLM-friendly project access | | `/deep-wiki:ado` | Generate a Node.js script to convert wiki to Azure DevOps Wiki-compatible format | | `/deep-wiki:build` | Package generated wiki as a VitePress site with dark theme | +| `/deep-wiki:deploy` | Generate GitHub Actions workflow to deploy wiki to GitHub Pages | ## Agents @@ -88,6 +89,9 @@ View available agents: `/agents` # Generate llms.txt for LLM-friendly access /deep-wiki:llms + +# Deploy wiki to GitHub Pages (optional) +/deep-wiki:deploy ``` ## How It Works @@ -104,6 +108,8 @@ Repository → Scan → Catalogue (JSON TOC) → Per-Section Pages → Assembled AGENTS.md Files (Only If Missing) ↓ llms.txt + llms-full.txt (LLM-friendly) + ↓ + GitHub Pages Deployment (Optional) ``` | Step | Component | What It Does | @@ -169,6 +175,7 @@ deep-wiki/ │ ├── onboard.md # Onboarding guide generation │ ├── agents.md # AGENTS.md generation (only if missing) │ ├── llms.md # llms.txt generation for LLM-friendly access +│ ├── deploy.md # GitHub Pages deployment workflow generation │ ├── ado.md # Azure DevOps Wiki export script generation │ └── build.md # VitePress site packaging ├── skills/ # Auto-invoked based on context diff --git a/.github/plugins/deep-wiki/commands/deploy.md b/.github/plugins/deep-wiki/commands/deploy.md new file mode 100644 index 0000000..8ec5e80 --- /dev/null +++ b/.github/plugins/deep-wiki/commands/deploy.md @@ -0,0 +1,178 @@ +--- +description: Generate a GitHub Actions workflow to deploy the VitePress wiki site to GitHub Pages +--- + +# Deep Wiki: Deploy to GitHub Pages + +Generate a `.github/workflows/deploy-wiki.yml` GitHub Actions workflow that builds and deploys the VitePress wiki to GitHub Pages. + +## Step 1: Check Prerequisites + +Before generating the workflow: + +1. **Verify wiki exists**: Check that `wiki/` directory and `wiki/package.json` exist + - If not, tell the user: _"Run `/deep-wiki:build` first to scaffold the VitePress site."_ +2. **Check for existing workflow**: Look for `.github/workflows/deploy-wiki.yml` + - If it exists, ask the user if they want to overwrite it + +## Step 2: Generate Workflow File + +Create `.github/workflows/deploy-wiki.yml`: + +```yaml +name: Deploy Wiki to GitHub Pages + +on: + push: + branches: [main] + paths: + - 'wiki/**' + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: 20 + cache: npm + cache-dependency-path: wiki/package-lock.json + + - name: Setup Pages + uses: actions/configure-pages@v5 + + - name: Install dependencies + run: npm ci + working-directory: wiki + + - name: Build with VitePress + run: npm run build + working-directory: wiki + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: wiki/.vitepress/dist + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + needs: build + runs-on: ubuntu-latest + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 +``` + +### Workflow Details + +| Setting | Value | Why | +|---------|-------|-----| +| **Trigger** | Push to `main` on `wiki/**` paths | Only rebuilds when wiki content changes | +| **Manual trigger** | `workflow_dispatch` | Allows manual re-deployment | +| **Node version** | 20 | LTS, required for VitePress 1.x | +| **Cache** | npm with `wiki/package-lock.json` | Speeds up subsequent builds | +| **Concurrency** | `pages` group, no cancel | Prevents parallel deploys | +| **Permissions** | `contents: read`, `pages: write`, `id-token: write` | Minimum required for Pages deployment | + +## Step 3: Update VitePress Config for GitHub Pages + +Check if `wiki/.vitepress/config.mts` needs a `base` path. GitHub Pages serves from: + +- **User/org site** (`username.github.io`): `base: '/'` (default, no change needed) +- **Project site** (`username.github.io/repo-name`): `base: '/repo-name/'` + +Detect which case applies: + +```bash +# Get the repo name +REPO_NAME=$(basename $(git remote get-url origin) .git) +OWNER=$(git remote get-url origin | sed -E 's|.*[:/]([^/]+)/[^/]+\.git|\\1|') +``` + +If the repo is NOT named `{owner}.github.io`, add the base path to `config.mts`: + +```typescript +export default defineConfig({ + base: '/{repo-name}/', + // ... rest of config +}) +``` + +## Step 4: Generate package-lock.json + +If `wiki/package-lock.json` doesn't exist (required for `npm ci` in CI): + +```bash +cd wiki && npm install +``` + +This generates the lock file. Remind the user to commit it. + +## Step 5: Commit and Report + +After generating the workflow, output: + +``` +## GitHub Pages Deployment Setup ✅ + +### Files Created +- `.github/workflows/deploy-wiki.yml` — GitHub Actions workflow + +### Files Modified +- `wiki/.vitepress/config.mts` — Added `base: '/{repo-name}/'` (if project site) + +### What You Need To Do + +1. **Commit the workflow file:** + ```bash + git add .github/workflows/deploy-wiki.yml wiki/package-lock.json + git commit -m "ci: add GitHub Pages deployment for wiki" + git push + ``` + +2. **Enable GitHub Pages in your repository settings:** + - Go to **Settings → Pages** + - Under **Build and deployment → Source**, select **GitHub Actions** + - That's it — no branch selection needed + +3. **Your wiki will be live at:** + - `https://{owner}.github.io/{repo-name}/` (project site) + - OR `https://{owner}.github.io/` (if repo is named `{owner}.github.io`) + +### Triggering Deployments +- **Automatic**: Every push to `main` that changes `wiki/**` files +- **Manual**: Go to Actions → "Deploy Wiki to GitHub Pages" → "Run workflow" +``` + +## Troubleshooting Guidance + +If the user reports issues, suggest checking: + +| Issue | Solution | +|-------|----------| +| 404 on deployed site | Verify `base` path in `config.mts` matches repo name | +| Build fails on `npm ci` | Ensure `wiki/package-lock.json` is committed | +| Pages not enabled | Go to Settings → Pages → Source → select "GitHub Actions" | +| Workflow not triggering | Check that changes are in `wiki/**` and pushed to `main` | +| Mermaid diagrams missing | Ensure `mermaid` and `vitepress-plugin-mermaid` are in `package.json` | + +$ARGUMENTS diff --git a/README.md b/README.md index b4d5193..44831cf 100644 --- a/README.md +++ b/README.md @@ -545,7 +545,7 @@ Plugins are installable packages containing curated sets of agents, commands, an | Plugin | Description | Commands | |--------|-------------|----------| -| [deep-wiki](.github/plugins/deep-wiki/) | AI-powered wiki generator with Mermaid diagrams, source citations, onboarding guides, AGENTS.md, and llms.txt | `/deep-wiki:generate`, `/deep-wiki:catalogue`, `/deep-wiki:page`, `/deep-wiki:research`, `/deep-wiki:ask`, `/deep-wiki:onboard`, `/deep-wiki:agents`, `/deep-wiki:llms`, `/deep-wiki:changelog`, `/deep-wiki:ado`, `/deep-wiki:build` | +| [deep-wiki](.github/plugins/deep-wiki/) | AI-powered wiki generator with Mermaid diagrams, source citations, onboarding guides, AGENTS.md, and llms.txt | `/deep-wiki:generate`, `/deep-wiki:catalogue`, `/deep-wiki:page`, `/deep-wiki:research`, `/deep-wiki:ask`, `/deep-wiki:onboard`, `/deep-wiki:agents`, `/deep-wiki:llms`, `/deep-wiki:changelog`, `/deep-wiki:ado`, `/deep-wiki:build`, `/deep-wiki:deploy` | --- diff --git a/docs-site/src/pages/index.astro b/docs-site/src/pages/index.astro index 055fced..557a1ff 100644 --- a/docs-site/src/pages/index.astro +++ b/docs-site/src/pages/index.astro @@ -131,6 +131,10 @@ import mcpServers from '../data/mcp-servers.json'; /deep-wiki:ado Export to Azure DevOps Wiki format +
+ /deep-wiki:deploy + Deploy wiki to GitHub Pages +
From 1e126edda08c22c30de0b55fe5110e9cdd5c9a7e Mon Sep 17 00:00:00 2001 From: Govind Kamtamneni Date: Thu, 12 Feb 2026 17:33:11 -0800 Subject: [PATCH 2/4] feat(deep-wiki): generate AGENTS.md in wiki/ folder - Add wiki/ to pertinent folders list (always generate) - Add wiki-specific AGENTS.md template with VitePress commands, content conventions, and wiki structure - Add AGENTS.md + CLAUDE.md to wiki/ folder structure in build.md - Update generate pipeline Step 7 to explicitly include wiki/ --- .github/plugins/deep-wiki/commands/agents.md | 43 +++++++++++++++++ .github/plugins/deep-wiki/commands/build.md | 2 + .../plugins/deep-wiki/commands/generate.md | 5 +- .../deep-wiki/skills/wiki-agents-md/SKILL.md | 48 +++++++++++++++++++ 4 files changed, 96 insertions(+), 2 deletions(-) diff --git a/.github/plugins/deep-wiki/commands/agents.md b/.github/plugins/deep-wiki/commands/agents.md index d81cb88..a4ef624 100644 --- a/.github/plugins/deep-wiki/commands/agents.md +++ b/.github/plugins/deep-wiki/commands/agents.md @@ -125,6 +125,49 @@ For each folder where AGENTS.md is missing, generate a file covering the **six c - Should NOT repeat root-level content - Should be concise — the root AGENTS.md handles the big picture +**Wiki AGENTS.md** (`wiki/AGENTS.md`) — ALWAYS generate for the wiki folder. Use this template: + +```markdown +# Wiki — Agent Instructions + +## Overview +Generated VitePress documentation site for this project. Contains architecture docs, onboarding guides, and API references with source-linked citations and dark-mode Mermaid diagrams. + +## Build & Run Commands +- Install: `npm install` +- Dev server: `npm run dev` +- Build: `npm run build` +- Preview: `npm run preview` + +## Wiki Structure +- `index.md` — Landing page with project overview and navigation +- `onboarding/` — Audience-tailored guides (contributor, staff engineer, executive, product manager) +- `{NN}-{section}/` — Numbered documentation sections +- `llms.txt` — LLM-friendly project summary (links + descriptions) +- `llms-full.txt` — LLM-friendly full content (inlined pages) +- `.vitepress/config.mts` — VitePress config with sidebar and Mermaid setup +- `.vitepress/theme/` — Dark theme (custom.css) and zoom handlers (index.ts) + +## Content Conventions +- All Mermaid diagrams use dark-mode colors (fills `#2d333b`, borders `#6d5dfc`, text `#e6edf3`) +- Every page has VitePress frontmatter (`title`, `description`) +- Citations link to source repository with line numbers +- Tables include a "Source" column with linked citations +- Mermaid diagrams followed by `` comment blocks + +## Boundaries +- ✅ **Always do:** Add new pages following existing section numbering, use dark-mode Mermaid colors +- ⚠️ **Ask first:** Change theme CSS, modify VitePress config, restructure sections +- 🚫 **Never do:** Delete generated pages without understanding dependencies, use light-mode colors, remove citation links + +## Documentation +- Wiki: `./` — This folder is the wiki +- LLM Context: `llms.txt` — Quick summary; `llms-full.txt` — Full content +- Onboarding: `onboarding/` — Four audience-tailored guides +``` + +Adapt this template to the actual project — fill in the real section names, technologies, and any project-specific conventions. + ### Step 5: Generate CLAUDE.md Companion Files For every folder where you generated an `AGENTS.md`, also create a `CLAUDE.md` in the same folder — **only if `CLAUDE.md` does not already exist**. diff --git a/.github/plugins/deep-wiki/commands/build.md b/.github/plugins/deep-wiki/commands/build.md index 75b55b2..c087d01 100644 --- a/.github/plugins/deep-wiki/commands/build.md +++ b/.github/plugins/deep-wiki/commands/build.md @@ -18,6 +18,8 @@ Create a `wiki/` directory with this structure: wiki/ ├── package.json ├── .gitignore +├── AGENTS.md # Agent instructions for wiki folder +├── CLAUDE.md # Companion pointer to AGENTS.md ├── index.md # Wiki home page (NOT a placeholder — see below) ├── llms.txt # LLM-friendly links + descriptions ├── llms-full.txt # LLM-friendly full inlined content diff --git a/.github/plugins/deep-wiki/commands/generate.md b/.github/plugins/deep-wiki/commands/generate.md index 85a9a1d..ca5d54c 100644 --- a/.github/plugins/deep-wiki/commands/generate.md +++ b/.github/plugins/deep-wiki/commands/generate.md @@ -105,14 +105,15 @@ Generate `AGENTS.md` files for pertinent repository folders. These files provide > **⚠️ CRITICAL: NEVER overwrite an existing AGENTS.md file.** For each folder, check if `AGENTS.md` already exists. If it does, skip it and report that it was skipped. -1. **Identify pertinent folders** — repository root, plus `tests/`, `src/`, `lib/`, `app/`, `packages/*/`, `services/*/`, and any folder with its own build manifest (`package.json`, `pyproject.toml`, `Cargo.toml`, `*.csproj`, `go.mod`) +1. **Identify pertinent folders** — repository root, `wiki/` (the generated VitePress site), plus `tests/`, `src/`, `lib/`, `app/`, `packages/*/`, `services/*/`, and any folder with its own build manifest (`package.json`, `pyproject.toml`, `Cargo.toml`, `*.csproj`, `go.mod`) 2. **For each folder**, check if `AGENTS.md` exists: - If YES → skip, report: `"✅ AGENTS.md already exists — skipping"` - If NO → analyze the folder's language, framework, build commands, test commands, conventions, and CI config 3. **Generate tailored AGENTS.md** covering the six core areas: Build & Run Commands (first!), Testing, Project Structure, Code Style, Git Workflow, and Boundaries (✅ always / ⚠️ ask first / 🚫 never) 4. **Generate CLAUDE.md companion** in every folder where AGENTS.md was created (only if `CLAUDE.md` doesn't already exist). Content is always: a heading, a generated-file comment, and a directive to read `AGENTS.md`. 5. **Root AGENTS.md** covers the whole project (tech stack, architecture, global conventions). **Nested AGENTS.md** covers folder-specific details only — don't repeat the root. -6. **Output a summary** listing which files were created, which were skipped (already exist), and which folders were not applicable. +6. **Wiki AGENTS.md** (`wiki/AGENTS.md`) — ALWAYS generate this for the wiki folder. It must cover: VitePress build/dev/preview commands, wiki structure (sections, onboarding, llms.txt), content conventions (Mermaid dark-mode rules, citation format, frontmatter), and boundaries (don't delete generated pages, don't modify theme without testing). Reference `wiki/llms.txt` and `wiki/llms-full.txt` in the Documentation section. +7. **Output a summary** listing which files were created, which were skipped (already exist), and which folders were not applicable. See `/deep-wiki:agents` for full AGENTS.md generation details. diff --git a/.github/plugins/deep-wiki/skills/wiki-agents-md/SKILL.md b/.github/plugins/deep-wiki/skills/wiki-agents-md/SKILL.md index 4706577..61c032c 100644 --- a/.github/plugins/deep-wiki/skills/wiki-agents-md/SKILL.md +++ b/.github/plugins/deep-wiki/skills/wiki-agents-md/SKILL.md @@ -40,6 +40,7 @@ Identify which folders should have an `AGENTS.md`: ### Always generate for: - **Repository root** (`/`) +- **Wiki folder** (`wiki/`) — if generated by deep-wiki (has `package.json` with VitePress) ### Generate if they exist: @@ -281,6 +282,53 @@ Covers that specific subfolder: - Folder-specific conventions - Should NOT repeat root-level content +### Wiki AGENTS.md (`wiki/AGENTS.md`) + +**ALWAYS generate this for the wiki folder.** The wiki is a VitePress project with its own `package.json` — it needs agent instructions. + +Use this template (adapt to the actual project): + +```markdown +# Wiki — Agent Instructions + +## Overview +Generated VitePress documentation site. Contains architecture docs, onboarding guides, and API references with source-linked citations and dark-mode Mermaid diagrams. + +## Build & Run +- Install: `npm install` +- Dev server: `npm run dev` +- Build: `npm run build` +- Preview: `npm run preview` + +## Wiki Structure +- `index.md` — Landing page with project overview and navigation +- `onboarding/` — Audience-tailored guides (contributor, staff engineer, executive, product manager) +- `{NN}-{section}/` — Numbered documentation sections +- `llms.txt` — LLM-friendly project summary (links + descriptions) +- `llms-full.txt` — LLM-friendly full content (inlined pages) +- `.vitepress/config.mts` — VitePress config with sidebar and Mermaid setup +- `.vitepress/theme/` — Dark theme (custom.css) and zoom handlers (index.ts) + +## Content Conventions +- All Mermaid diagrams use dark-mode colors (fills `#2d333b`, borders `#6d5dfc`, text `#e6edf3`) +- Every page has VitePress frontmatter (`title`, `description`) +- Citations link to source repository with line numbers +- Tables include a "Source" column with linked citations +- Mermaid diagrams followed by `` comment blocks + +## Boundaries +- ✅ **Always do:** Add new pages following existing section numbering, use dark-mode Mermaid colors +- ⚠️ **Ask first:** Change theme CSS, modify VitePress config, restructure sections +- 🚫 **Never do:** Delete generated pages without understanding dependencies, use light-mode colors, remove citation links + +## Documentation +- Wiki: `./` — This folder is the wiki +- LLM Context: `llms.txt` — Quick summary; `llms-full.txt` — Full content +- Onboarding: `onboarding/` — Four audience-tailored guides +``` + +Fill in the real section names, technologies, and project-specific conventions. + Agents read the nearest AGENTS.md in the directory tree. Nested files take precedence, so they should contain folder-specific details, not global ones. ## CLAUDE.md Companion File From 4cf58ce31ea6e814a21ff4db46b5f52391ba8bfc Mon Sep 17 00:00:00 2001 From: Govind Kamtamneni Date: Thu, 12 Feb 2026 18:28:22 -0800 Subject: [PATCH 3/4] fix(deep-wiki): developer homepage, AGENTS.md guard, mermaid zoom, focus mode MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. Homepage: Remove marketing hero layout, use developer-focused template with Quick Start commands, architecture diagram, documentation map, key files table, and tech stack summary. No hero: frontmatter. 2. AGENTS.md: Fix 'ALWAYS generate' to 'only if missing' guard for wiki/ folder across generate.md, agents.md, and wiki-agents-md skill. 3. Deploy: Strengthen workflow existence check — search for ANY pages workflow, not just deploy-wiki.yml. Prominent warning about enabling GitHub Pages via Actions in settings. 4. Mermaid zoom: Replace vague instructions with complete TypeScript implementation — click-to-expand modal with zoom controls, scroll wheel zoom, pan, keyboard shortcuts (Esc/+/-/0), viewBox fix, async SVG polling. Full CSS for overlay, controls, hover hints. 5. Focus mode: Add reading focus mode toggle (eye button, F key shortcut) that hides sidebar, navbar, footer, and aside for distraction-free reading. Full CSS for focus-mode state. --- .github/plugins/deep-wiki/commands/agents.md | 2 +- .github/plugins/deep-wiki/commands/build.md | 408 +++++++++++++++++- .github/plugins/deep-wiki/commands/deploy.md | 23 +- .../plugins/deep-wiki/commands/generate.md | 4 +- .../deep-wiki/skills/wiki-agents-md/SKILL.md | 2 +- 5 files changed, 408 insertions(+), 31 deletions(-) diff --git a/.github/plugins/deep-wiki/commands/agents.md b/.github/plugins/deep-wiki/commands/agents.md index a4ef624..c7c783c 100644 --- a/.github/plugins/deep-wiki/commands/agents.md +++ b/.github/plugins/deep-wiki/commands/agents.md @@ -125,7 +125,7 @@ For each folder where AGENTS.md is missing, generate a file covering the **six c - Should NOT repeat root-level content - Should be concise — the root AGENTS.md handles the big picture -**Wiki AGENTS.md** (`wiki/AGENTS.md`) — ALWAYS generate for the wiki folder. Use this template: +**Wiki AGENTS.md** (`wiki/AGENTS.md`) — Generate for the wiki folder if it doesn't already exist (same only-if-missing guard). Use this template: ```markdown # Wiki — Agent Instructions diff --git a/.github/plugins/deep-wiki/commands/build.md b/.github/plugins/deep-wiki/commands/build.md index c087d01..e75dc9a 100644 --- a/.github/plugins/deep-wiki/commands/build.md +++ b/.github/plugins/deep-wiki/commands/build.md @@ -45,17 +45,77 @@ wiki/ ### index.md — Wiki Landing Page (CRITICAL) -The `index.md` MUST be a proper, content-rich wiki home page — **NEVER a generic placeholder**. It serves as the main entry point for both VitePress and ADO Wiki exports. +The `index.md` MUST be a developer-focused wiki home page — **NOT a marketing landing page**. No `hero:` frontmatter blocks, no taglines, no call-to-action buttons. This is a technical wiki, not a product page. -Generate `index.md` with: -- **Project title** as `# heading` -- **Overview paragraph** — what the project does, its purpose, key technologies (1-2 sentences) -- **Quick Navigation table** — Section, Description columns linking to all top-level wiki sections -- **Links to onboarding guides** (if they exist) — prominently placed -- **Architecture overview diagram** — a high-level Mermaid `graph LR` showing major system components (reuse from the architecture page) -- **Key technologies table** — Technology, Purpose, Source columns +Generate `index.md` with this structure: -For VitePress, the `index.md` can optionally include a `hero:` block in front matter, but the markdown body below it must contain the full landing page content (so it survives ADO conversion which strips front matter). +```markdown +--- +title: Project Name — Documentation +description: Technical documentation for Project Name +--- + +# Project Name + +Brief 1–2 sentence description of what the project does technically. + +## Quick Start + +\`\`\`bash +# Clone, install, run (actual commands from the repo) +git clone +cd +npm install && npm run dev +\`\`\` + +## Architecture Overview + +\`\`\`mermaid +graph LR + A[Component A] --> B[Component B] + B --> C[Component C] +\`\`\` + + +## Documentation Map + +| Section | Description | +|---------|-------------| +| [Onboarding](./onboarding/) | Guides for contributors, staff engineers, executives, and PMs | +| [Getting Started](./01-getting-started/) | Setup, configuration, first steps | +| [Architecture](./02-architecture/) | System design, data flow, components | +| ... | ... | + +## Key Files + +| File | Purpose | Source | +|------|---------|--------| +| `src/main.ts` | Application entry point | [src/main.ts:1](REPO_URL/blob/BRANCH/src/main.ts#L1) | +| `src/config.ts` | Configuration loader | [src/config.ts:1](REPO_URL/blob/BRANCH/src/config.ts#L1) | +| ... | ... | ... | + +## Tech Stack + +| Technology | Purpose | +|-----------|---------| +| TypeScript | Primary language | +| FastAPI | API framework | +| ... | ... | +``` + +**DO NOT include:** +- VitePress `hero:` frontmatter (no hero banners, no action buttons) +- Marketing copy ("powerful", "blazing fast", "enterprise-grade") +- Feature highlight cards or badges +- "Get Started" call-to-action buttons +- Any content that feels like a product landing page + +**DO include:** +- Actual runnable commands in Quick Start +- Architecture diagram with source citations +- Documentation map table linking to all wiki sections +- Key files table with source citations +- Tech stack summary table ### package.json @@ -159,7 +219,7 @@ Scan the generated markdown files and build sidebar config: ## Step 3: Theme Setup (theme/index.ts) -Implement two zoom systems: +Implement two zoom systems and a focus mode toggle: ### Image Zoom (medium-zoom) ```typescript @@ -167,20 +227,204 @@ import mediumZoom from 'medium-zoom' // Apply to all images: mediumZoom('.vp-doc img:not(.no-zoom)', { background: 'rgba(0, 0, 0, 0.92)' }) ``` -### Mermaid Diagram Zoom (custom SVG overlay) +### Mermaid Diagram Zoom (custom SVG overlay — CRITICAL) + +Mermaid renders ``, not ``, so medium-zoom won't work. You MUST implement a custom fullscreen overlay. **This is the most common source of bugs — follow this implementation exactly.** + +```typescript +// In setup() within enhanceApp or theme index.ts +import { onMounted, watch, nextTick } from 'vue' +import { useRoute } from 'vitepress' +import DefaultTheme from 'vitepress/theme' +import mediumZoom from 'medium-zoom' +import './custom.css' + +export default { + extends: DefaultTheme, + setup() { + const route = useRoute() + + const initZoom = () => { + // Image zoom + mediumZoom('.vp-doc img:not(.no-zoom)', { + background: 'rgba(0, 0, 0, 0.92)', + }) + + // Mermaid diagram zoom — poll for async-rendered SVGs + const attachMermaidZoom = (retries = 0) => { + const diagrams = document.querySelectorAll('.mermaid') + if (diagrams.length === 0 && retries < 20) { + setTimeout(() => attachMermaidZoom(retries + 1), 500) + return + } + + diagrams.forEach((container) => { + // Skip if already has zoom handler + if (container.getAttribute('data-zoom-attached')) return + container.setAttribute('data-zoom-attached', 'true') + container.style.cursor = 'pointer' + + container.addEventListener('click', () => { + const svg = container.querySelector('svg') + if (!svg) return + openDiagramModal(svg) + }) + }) + } + attachMermaidZoom() + } + + const openDiagramModal = (svg: SVGSVGElement) => { + // Create overlay + const overlay = document.createElement('div') + overlay.className = 'diagram-zoom-overlay' + + // Create container with controls + const wrapper = document.createElement('div') + wrapper.className = 'diagram-zoom-wrapper' + + // Controls bar + const controls = document.createElement('div') + controls.className = 'diagram-zoom-controls' + controls.innerHTML = ` + + + + + ` + + // Clone SVG into scrollable content area + const content = document.createElement('div') + content.className = 'diagram-zoom-content' + const cloned = svg.cloneNode(true) as SVGSVGElement + + // Fix viewBox if missing + if (!cloned.getAttribute('viewBox')) { + const bbox = svg.getBBox() + cloned.setAttribute('viewBox', `${bbox.x} ${bbox.y} ${bbox.width} ${bbox.height}`) + } + cloned.style.width = '100%' + cloned.style.height = 'auto' + cloned.style.maxHeight = 'none' + + content.appendChild(cloned) + wrapper.appendChild(controls) + wrapper.appendChild(content) + overlay.appendChild(wrapper) + document.body.appendChild(overlay) + document.body.style.overflow = 'hidden' + + // Zoom state + let scale = 1 + let translateX = 0 + let translateY = 0 + const applyTransform = () => { + content.style.transform = `translate(${translateX}px, ${translateY}px) scale(${scale})` + } + + // Control buttons + controls.addEventListener('click', (e) => { + const action = (e.target as HTMLElement).closest('[data-action]')?.getAttribute('data-action') + if (action === 'zoom-in') { scale = Math.min(scale * 1.3, 5); applyTransform() } + if (action === 'zoom-out') { scale = Math.max(scale / 1.3, 0.2); applyTransform() } + if (action === 'zoom-reset') { scale = 1; translateX = 0; translateY = 0; applyTransform() } + if (action === 'close') closeOverlay() + }) + + // Scroll wheel zoom + overlay.addEventListener('wheel', (e) => { + e.preventDefault() + const delta = e.deltaY > 0 ? 0.9 : 1.1 + scale = Math.min(Math.max(scale * delta, 0.2), 5) + applyTransform() + }, { passive: false }) + + // Pan with mouse drag + let isPanning = false + let startX = 0, startY = 0 + content.addEventListener('mousedown', (e) => { + isPanning = true; startX = e.clientX - translateX; startY = e.clientY - translateY + content.style.cursor = 'grabbing' + }) + document.addEventListener('mousemove', (e) => { + if (!isPanning) return + translateX = e.clientX - startX; translateY = e.clientY - startY + applyTransform() + }) + document.addEventListener('mouseup', () => { + isPanning = false; content.style.cursor = 'grab' + }) + + // Keyboard shortcuts + const keyHandler = (e: KeyboardEvent) => { + if (e.key === 'Escape') closeOverlay() + if (e.key === '+' || e.key === '=') { scale = Math.min(scale * 1.3, 5); applyTransform() } + if (e.key === '-') { scale = Math.max(scale / 1.3, 0.2); applyTransform() } + if (e.key === '0') { scale = 1; translateX = 0; translateY = 0; applyTransform() } + } + document.addEventListener('keydown', keyHandler) + + // Backdrop click to close + overlay.addEventListener('click', (e) => { + if (e.target === overlay) closeOverlay() + }) + + const closeOverlay = () => { + document.removeEventListener('keydown', keyHandler) + document.body.style.overflow = '' + overlay.remove() + } + } + + onMounted(() => initZoom()) + watch(() => route.path, () => nextTick(() => initZoom())) + }, +} +``` -Mermaid renders ``, not ``, so medium-zoom won't work. Build a custom fullscreen overlay: -- **Clone the SVG** (don't move it) into the overlay -- **Zoom controls**: +, −, Reset buttons + keyboard shortcuts (+, -, 0) -- **Scroll wheel zoom**: Passive-false wheel event listener -- **Pan**: Mousedown drag on the content area -- **Keyboard**: Escape to close -- **Backdrop click**: Click outside to close -- **ViewBox fix**: If SVG has no viewBox, compute one from `getBBox()` +**CRITICAL implementation notes:** +- Use `setup()` with `onMounted` + route watcher — NOT `enhanceApp()` (DOM doesn't exist during SSR) +- **Poll for Mermaid SVGs** with retry (up to 20 × 500ms) — `vitepress-plugin-mermaid` renders asynchronously, SVGs don't exist when `onMounted` fires +- **Clone the SVG** (don't move it) — moving it breaks the page layout +- **Fix missing viewBox** — compute from `getBBox()` so scaling works correctly +- **Mark containers** with `data-zoom-attached` to prevent duplicate handlers on route changes -**CRITICAL**: Use `setup()` with `onMounted` + route watcher, NOT `enhanceApp()` (DOM doesn't exist yet during SSR). +### Focus Mode Toggle -**Mermaid async rendering**: Diagrams are rendered asynchronously by `vitepress-plugin-mermaid`. The SVGs don't exist when `onMounted` fires. **Poll for them** with retry (up to 20 attempts × 500ms). +Add a reading focus mode that hides sidebar and navbar for distraction-free reading: + +```typescript +// Add this inside setup(), after initZoom +const initFocusMode = () => { + // Don't add if already exists + if (document.getElementById('focus-mode-toggle')) return + + const btn = document.createElement('button') + btn.id = 'focus-mode-toggle' + btn.className = 'focus-mode-btn' + btn.title = 'Toggle focus mode (F)' + btn.textContent = '👁' + btn.addEventListener('click', toggleFocusMode) + document.body.appendChild(btn) + + // Keyboard shortcut: F key + document.addEventListener('keydown', (e) => { + if (e.key === 'f' && !e.ctrlKey && !e.metaKey && !e.altKey + && !['INPUT', 'TEXTAREA', 'SELECT'].includes((e.target as HTMLElement).tagName)) { + e.preventDefault() + toggleFocusMode() + } + }) +} + +const toggleFocusMode = () => { + document.body.classList.toggle('focus-mode') + const btn = document.getElementById('focus-mode-toggle') + if (btn) btn.textContent = document.body.classList.contains('focus-mode') ? '👁‍🗨' : '👁' +} + +onMounted(() => { initZoom(); initFocusMode() }) +``` ## Step 4: Dark Theme CSS (theme/custom.css) @@ -239,6 +483,128 @@ Theme variables don't cover everything. Force dark fills on all SVG shapes: - Image hover: subtle glow + scale on hover - medium-zoom overlay: dark background with blur +```css +/* === Mermaid Hover Hint === */ +.mermaid { + cursor: pointer; + transition: box-shadow 0.2s ease; + position: relative; +} +.mermaid:hover { + box-shadow: 0 0 0 2px #6d5dfc40, 0 0 20px #6d5dfc20; +} +.mermaid::after { + content: '🔍 Click to zoom'; + position: absolute; + bottom: 8px; + right: 8px; + background: #2d333b; + color: #8b949e; + padding: 2px 8px; + border-radius: 4px; + font-size: 11px; + opacity: 0; + transition: opacity 0.2s ease; + pointer-events: none; +} +.mermaid:hover::after { opacity: 1; } + +/* === Diagram Zoom Overlay === */ +.diagram-zoom-overlay { + position: fixed; + inset: 0; + z-index: 9999; + background: rgba(0, 0, 0, 0.85); + backdrop-filter: blur(4px); + display: flex; + align-items: center; + justify-content: center; +} +.diagram-zoom-wrapper { + display: flex; + flex-direction: column; + width: 90vw; + height: 90vh; + background: #0d1117; + border: 1px solid #30363d; + border-radius: 12px; + overflow: hidden; +} +.diagram-zoom-controls { + display: flex; + gap: 8px; + padding: 8px 12px; + background: #161b22; + border-bottom: 1px solid #30363d; +} +.zoom-btn { + background: #2d333b; + color: #e6edf3; + border: 1px solid #30363d; + border-radius: 6px; + padding: 4px 12px; + cursor: pointer; + font-size: 14px; +} +.zoom-btn:hover { background: #3d434b; border-color: #6d5dfc; } +.zoom-close { margin-left: auto; } +.diagram-zoom-content { + flex: 1; + overflow: hidden; + display: flex; + align-items: center; + justify-content: center; + cursor: grab; + transform-origin: center center; +} +.diagram-zoom-content svg { max-width: none; } + +/* === Focus Mode Button === */ +.focus-mode-btn { + position: fixed; + bottom: 20px; + right: 20px; + z-index: 100; + width: 40px; + height: 40px; + border-radius: 50%; + background: #2d333b; + border: 1px solid #30363d; + color: #e6edf3; + font-size: 18px; + cursor: pointer; + display: flex; + align-items: center; + justify-content: center; + transition: all 0.2s ease; + box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3); +} +.focus-mode-btn:hover { + background: #3d434b; + border-color: #6d5dfc; + transform: scale(1.1); +} + +/* === Focus Mode Active State === */ +.focus-mode .VPSidebar, +.focus-mode .VPNav, +.focus-mode .VPLocalNav, +.focus-mode .VPFooter, +.focus-mode .VPDocAside { + display: none !important; +} +.focus-mode .VPDoc { + padding: 0 !important; +} +.focus-mode .VPDoc .container { + max-width: 900px !important; + margin: 0 auto !important; +} +.focus-mode .vp-doc { + padding: 40px 20px !important; +} +``` + ## Step 5: Post-Processing (Markdown Fixes) Before building, fix common issues in generated markdown: diff --git a/.github/plugins/deep-wiki/commands/deploy.md b/.github/plugins/deep-wiki/commands/deploy.md index 8ec5e80..19979f7 100644 --- a/.github/plugins/deep-wiki/commands/deploy.md +++ b/.github/plugins/deep-wiki/commands/deploy.md @@ -12,8 +12,16 @@ Before generating the workflow: 1. **Verify wiki exists**: Check that `wiki/` directory and `wiki/package.json` exist - If not, tell the user: _"Run `/deep-wiki:build` first to scaffold the VitePress site."_ -2. **Check for existing workflow**: Look for `.github/workflows/deploy-wiki.yml` - - If it exists, ask the user if they want to overwrite it +2. **Check for existing deployment workflows**: Search for ANY existing GitHub Pages workflow: + ```bash + # Check for exact file + ls .github/workflows/deploy-wiki.yml 2>/dev/null + # Check for any pages-related workflow + grep -rl "deploy-pages\|pages-artifact\|github-pages" .github/workflows/ 2>/dev/null + ``` + - If `deploy-wiki.yml` exists → **STOP**. Tell the user: _"A deployment workflow already exists at `.github/workflows/deploy-wiki.yml`. No changes needed."_ + - If a DIFFERENT pages workflow exists → **ASK the user**: _"I found an existing GitHub Pages workflow at `{path}`. Should I skip creating a new one, or create `deploy-wiki.yml` alongside it?"_ + - If no pages workflow exists → proceed with generation ## Step 2: Generate Workflow File @@ -142,6 +150,8 @@ After generating the workflow, output: ### What You Need To Do +> ⚠️ IMPORTANT: GitHub Pages will NOT work until you complete step 2. + 1. **Commit the workflow file:** ```bash git add .github/workflows/deploy-wiki.yml wiki/package-lock.json @@ -149,10 +159,11 @@ After generating the workflow, output: git push ``` -2. **Enable GitHub Pages in your repository settings:** - - Go to **Settings → Pages** - - Under **Build and deployment → Source**, select **GitHub Actions** - - That's it — no branch selection needed +2. **Enable GitHub Pages (REQUIRED — deployments will fail without this):** + - Go to your repo on GitHub → **Settings** → **Pages** + - Under **Build and deployment**, change **Source** to **"GitHub Actions"** + - Click **Save** + - Without this step, the workflow runs but the site is NOT published 3. **Your wiki will be live at:** - `https://{owner}.github.io/{repo-name}/` (project site) diff --git a/.github/plugins/deep-wiki/commands/generate.md b/.github/plugins/deep-wiki/commands/generate.md index ca5d54c..16fecd4 100644 --- a/.github/plugins/deep-wiki/commands/generate.md +++ b/.github/plugins/deep-wiki/commands/generate.md @@ -95,7 +95,7 @@ Scaffold a complete VitePress project in `wiki/` with: - Click-to-zoom for diagrams (custom SVG overlay with pan/zoom) and images (medium-zoom) - Dynamic sidebar from catalogue structure - Onboarding section first (uncollapsed) -- **Proper `index.md` landing page** — NOT a placeholder. Must contain project title, overview, quick navigation table linking to all sections, and links to onboarding guides. +- **Proper `index.md` landing page** — Developer-focused, NOT a marketing page. No `hero:` frontmatter. Must contain: Quick Start with runnable commands, architecture overview diagram, documentation map table linking to all sections, key files table with source citations, and tech stack summary. See `/deep-wiki:build` for full template. See `/deep-wiki:build` for full VitePress packaging details. @@ -112,7 +112,7 @@ Generate `AGENTS.md` files for pertinent repository folders. These files provide 3. **Generate tailored AGENTS.md** covering the six core areas: Build & Run Commands (first!), Testing, Project Structure, Code Style, Git Workflow, and Boundaries (✅ always / ⚠️ ask first / 🚫 never) 4. **Generate CLAUDE.md companion** in every folder where AGENTS.md was created (only if `CLAUDE.md` doesn't already exist). Content is always: a heading, a generated-file comment, and a directive to read `AGENTS.md`. 5. **Root AGENTS.md** covers the whole project (tech stack, architecture, global conventions). **Nested AGENTS.md** covers folder-specific details only — don't repeat the root. -6. **Wiki AGENTS.md** (`wiki/AGENTS.md`) — ALWAYS generate this for the wiki folder. It must cover: VitePress build/dev/preview commands, wiki structure (sections, onboarding, llms.txt), content conventions (Mermaid dark-mode rules, citation format, frontmatter), and boundaries (don't delete generated pages, don't modify theme without testing). Reference `wiki/llms.txt` and `wiki/llms-full.txt` in the Documentation section. +6. **Wiki AGENTS.md** (`wiki/AGENTS.md`) — Generate this for the wiki folder **only if it doesn't already exist** (same guard as all other AGENTS.md files). It must cover: VitePress build/dev/preview commands, wiki structure (sections, onboarding, llms.txt), content conventions (Mermaid dark-mode rules, citation format, frontmatter), and boundaries (don't delete generated pages, don't modify theme without testing). Reference `wiki/llms.txt` and `wiki/llms-full.txt` in the Documentation section. 7. **Output a summary** listing which files were created, which were skipped (already exist), and which folders were not applicable. See `/deep-wiki:agents` for full AGENTS.md generation details. diff --git a/.github/plugins/deep-wiki/skills/wiki-agents-md/SKILL.md b/.github/plugins/deep-wiki/skills/wiki-agents-md/SKILL.md index 61c032c..4ef1d7b 100644 --- a/.github/plugins/deep-wiki/skills/wiki-agents-md/SKILL.md +++ b/.github/plugins/deep-wiki/skills/wiki-agents-md/SKILL.md @@ -284,7 +284,7 @@ Covers that specific subfolder: ### Wiki AGENTS.md (`wiki/AGENTS.md`) -**ALWAYS generate this for the wiki folder.** The wiki is a VitePress project with its own `package.json` — it needs agent instructions. +**ALWAYS check** if `wiki/AGENTS.md` exists before generating — same only-if-missing guard as all other folders. If it exists, skip it. Use this template (adapt to the actual project): From 6142f8e60ac58372845c0fcdd2dbf043cd1bb698 Mon Sep 17 00:00:00 2001 From: Govind Kamtamneni Date: Thu, 12 Feb 2026 18:38:36 -0800 Subject: [PATCH 4/4] feat(deep-wiki): add cross-references between wiki pages - Inline links: mention of a concept on another page becomes a relative Markdown link (e.g., [Data Flow](../02-architecture/data-flow.md)) - Related Pages section: every page ends with a table of connected pages showing page name + relationship description - Anchor links: link to specific sections with #heading-anchor - Bidirectional: if A links to B, B should link back to A - Updated: page.md, generate.md, wiki-page-writer skill, wiki-writer agent - Added to validation checklist in wiki-writer agent --- .../plugins/deep-wiki/agents/wiki-writer.md | 2 ++ .github/plugins/deep-wiki/commands/generate.md | 1 + .github/plugins/deep-wiki/commands/page.md | 1 + .../deep-wiki/skills/wiki-page-writer/SKILL.md | 18 +++++++++++++++++- 4 files changed, 21 insertions(+), 1 deletion(-) diff --git a/.github/plugins/deep-wiki/agents/wiki-writer.md b/.github/plugins/deep-wiki/agents/wiki-writer.md index 29a8c92..aa1be70 100644 --- a/.github/plugins/deep-wiki/agents/wiki-writer.md +++ b/.github/plugins/deep-wiki/agents/wiki-writer.md @@ -53,6 +53,7 @@ When generating a documentation page, you ALWAYS follow this sequence: - **Minimum 3–5 Mermaid diagrams per page** (scaled by scope), each followed by a `` comment block - **Diagram variety**: Each page MUST use at least 2 different diagram types — don't just repeat `graph TB`. Mix architecture graphs, sequence diagrams, class diagrams, state machines, ER diagrams, and flowcharts as appropriate - Minimum 5 source file citations per page using linked format (see Citation Format above) +- **Cross-reference related wiki pages** inline using relative Markdown links (e.g., `[Data Flow](../02-architecture/data-flow.md)`) and end each page with a "Related Pages" table - Use `autonumber` in all sequence diagrams - Explain WHY, not just WHAT - Every section must add value — no filler content @@ -117,4 +118,5 @@ Before finishing any page: - [ ] All citations use correct format (linked for remote repos, local otherwise) - [ ] At least 2 Mermaid diagrams present - [ ] At least 5 different source files cited +- [ ] Cross-references to related wiki pages included (inline links + Related Pages section) - [ ] No claims without code references diff --git a/.github/plugins/deep-wiki/commands/generate.md b/.github/plugins/deep-wiki/commands/generate.md index 16fecd4..4035e2b 100644 --- a/.github/plugins/deep-wiki/commands/generate.md +++ b/.github/plugins/deep-wiki/commands/generate.md @@ -76,6 +76,7 @@ For each leaf node in the catalogue, generate a full documentation page: - Cite at least 5 different source files per page using the resolved citation format (linked or local) - Use Markdown tables for APIs, config options, and component summaries — include "Source" column with citations - **Tables over prose**: Convert any list of structured items into a table. Use comparison tables for technologies and alternatives. +- **Cross-references between pages**: When a page mentions a concept, component, or pattern documented on another wiki page, link to it with a relative Markdown link (e.g., `[Authentication](../02-architecture/authentication.md)`). Add a "Related Pages" section at the end of each page listing connected wiki pages with one-line descriptions. - End with a References section ### Step 5: Post-Processing & Validation diff --git a/.github/plugins/deep-wiki/commands/page.md b/.github/plugins/deep-wiki/commands/page.md index 4f0f48d..81389bd 100644 --- a/.github/plugins/deep-wiki/commands/page.md +++ b/.github/plugins/deep-wiki/commands/page.md @@ -65,6 +65,7 @@ Structure the page with: - **Implementation Details**: key algorithms, error handling, state management - **Configuration & Deployment**: use tables for config options (Key, Default, Description, Source) - **References**: inline citations throughout using resolved format +- **Cross-references**: Link to related wiki pages using relative Markdown links (e.g., `[Data Flow](../02-architecture/data-flow.md)`). Whenever a concept, component, or pattern is covered in more depth on another wiki page, link to it inline. Also add a "Related Pages" section at the end listing connected wiki pages. ### Content Organization Rules diff --git a/.github/plugins/deep-wiki/skills/wiki-page-writer/SKILL.md b/.github/plugins/deep-wiki/skills/wiki-page-writer/SKILL.md index 874ad2f..7088aa9 100644 --- a/.github/plugins/deep-wiki/skills/wiki-page-writer/SKILL.md +++ b/.github/plugins/deep-wiki/skills/wiki-page-writer/SKILL.md @@ -71,7 +71,7 @@ description: "One-line description" - **Tables**: Include a "Source" column with linked citations when listing components, APIs, or configurations ### Structure -- Overview (explain WHY) → Architecture → Components → Data Flow → Implementation → References +- Overview (explain WHY) → Architecture → Components → Data Flow → Implementation → References → Related Pages - **Use tables aggressively** — prefer tables over prose for any structured information (APIs, configs, components, comparisons) - **Summary tables first**: Start each major section with an at-a-glance summary table before details - Use comparison tables when introducing technologies or patterns — always compare side-by-side @@ -80,6 +80,22 @@ description: "One-line description" - Include pseudocode in a familiar language when explaining complex code paths - **Progressive disclosure**: Start with the big picture, then drill into specifics — don't front-load details +### Cross-References Between Wiki Pages +- **Inline links**: When mentioning a concept, component, or pattern covered on another wiki page, link to it inline using relative Markdown links: `[Component Name](../NN-section/page-name.md)` or `[Section Title](../NN-section/page-name.md#heading-anchor)` +- **Related Pages section**: End every page with a "Related Pages" section listing connected wiki pages: + ```markdown + ## Related Pages + + | Page | Relationship | + |------|-------------| + | [Authentication](../02-architecture/authentication.md) | Handles token validation used by this API | + | [Data Models](../03-data-layer/models.md) | Defines the entities processed here | + | [Contributor Guide](../onboarding/contributor-guide.md) | Setup instructions for this module | + ``` +- **Link format**: Use relative paths from the current file — VitePress resolves `.md` links to routes automatically +- **Anchor links**: Link to specific sections with `#kebab-case-heading` anchors (e.g., `[error handling](../02-architecture/overview.md#error-handling)`) +- **Bidirectional where possible**: If page A links to page B, page B should link back to page A + ### VitePress Compatibility - Escape bare generics outside code fences: `` `List` `` not bare `List` - No `
` in Mermaid blocks