@iamdangavin/claude-skill-vitepress-docs 1.9.0 → 3.0.0

package/{skill/SKILL.md → commands/vitedocs/init.md}

@@ -1,7 +1,7 @@
 ---
-name: vitepress:docs
-description: VitePress documentation suite — setup GitHub Pages deployment, generate docs from a codebase, capture screenshots of any running app, and sync docs as code changes.
-argument-hint: [mode: setup|generate|screenshot|sync] or omit to be prompted
+name: vitedocs:init
+description: VitePress documentation suite — prompts for which mode to run and proceeds directly.
+argument-hint: [setup|generate|screenshot|sync|brand|update] or omit to be prompted
 allowed-tools:
   - Read
   - Write
@@ -12,17 +12,21 @@ allowed-tools:
   - AskUserQuestion
 ---
 
-# Skill: vitepress:docs
+# vitedocs:init
 
-Four modes for full VitePress documentation lifecycle. If no mode is given as an argument, use AskUserQuestion to prompt for one:
+If a mode was passed as an argument, proceed directly to that mode's instructions below. Otherwise use AskUserQuestion:
 
-- header: "vitepress:docs"
+- header: "vitedocs"
 - question: "Which mode do you need?"
 - options:
   - "setup — Wire up VitePress + GitHub Actions for Pages deployment"
   - "generate — Analyze the codebase and write documentation pages"
   - "screenshot — Capture real screenshots and replace placeholders"
   - "sync — Detect code drift and update docs that are out of date"
+  - "brand — Configure colors, fonts, logo, and visual identity"
+  - "update — Retrofit an existing docs setup with the latest components"
+
+Once a mode is selected, execute that mode's full instructions inline — do not ask the user to run a different command. The complete instructions for every mode follow below.
 
 ---
 
@@ -159,7 +163,7 @@ Present the relevant checklist as plain text, then use AskUserQuestion to confir
   - "Not yet — I need more time"
   - "I have a question"
 
-If "Not yet": tell the user to run `/vitepress:docs setup` again when ready and exit.
+If "Not yet": tell the user to run `/vitedocs:setup` again when ready and exit.
 If "I have a question": answer it, then re-ask this question.
 
 The checklist to present (tailor to their answers):
@@ -588,13 +592,13 @@ If `apiBase` was collected in Q1b, write the following files before updating the
           @click="activeTab = tab"
         >{{ tab }}</button>
       </div>
-      <pre class="api-ep__code"><code>{{ currentSample }}</code></pre>
+      <pre class="api-ep__code"><code v-html="highlightedSample"></code></pre>
       <p v-if="activeTab === 'Fetch'" class="api-ep__note">
         Must be called from an authenticated browser session — cookies are sent automatically.
       </p>
       <template v-if="response">
         <div class="api-ep__section-label">Sample Response</div>
-        <pre class="api-ep__code"><code>{{ formattedResponse }}</code></pre>
+        <pre class="api-ep__code"><code v-html="highlightedResponse"></code></pre>
       </template>
     </div>
   </div>
@@ -603,6 +607,19 @@ If `apiBase` was collected in Q1b, write the following files before updating the
 <script setup>
 import { ref, computed } from 'vue'
 import { useData } from 'vitepress'
+import hljs from 'highlight.js/lib/core'
+import javascript from 'highlight.js/lib/languages/javascript'
+import bash from 'highlight.js/lib/languages/bash'
+import json from 'highlight.js/lib/languages/json'
+// ADD THESE ONLY IF THE CORRESPONDING TAB WAS SELECTED IN Q1b:
+// import php from 'highlight.js/lib/languages/php'
+// import python from 'highlight.js/lib/languages/python'
+
+hljs.registerLanguage('javascript', javascript) // Fetch + Axios
+hljs.registerLanguage('bash', bash)             // cURL
+hljs.registerLanguage('json', json)             // response bodies
+// hljs.registerLanguage('php', php)
+// hljs.registerLanguage('python', python)
 
 const props = defineProps({
   method: { type: String, required: true },
@@ -658,9 +675,32 @@ const currentSample = computed(() => {
   return ''
 })
 
+const tabLang = {
+  'Fetch': 'javascript',
+  'Axios': 'javascript',
+  'cURL': 'bash',
+  'PHP': 'php',
+  'Python': 'python',
+}
+
+const highlight = (code, lang) => {
+  const registered = hljs.getLanguage(lang)
+  return registered
+    ? hljs.highlight(code, { language: lang }).value
+    : hljs.highlightAuto(code).value
+}
+
+const highlightedSample = computed(() =>
+  highlight(currentSample.value, tabLang[activeTab.value] ?? 'bash')
+)
+
 const formattedResponse = computed(() =>
   props.response ? JSON.stringify(props.response, null, 2) : ''
 )
+
+const highlightedResponse = computed(() =>
+  formattedResponse.value ? highlight(formattedResponse.value, 'json') : ''
+)
 </script>
 
 <style scoped>
@@ -686,10 +726,10 @@ const formattedResponse = computed(() =>
 </style>
 ```
 
-**Install `medium-zoom`** in the docs folder:
+**Install dependencies** in the docs folder:
 
 ```bash
-cd DOCS_FOLDER && npm install medium-zoom
+cd DOCS_FOLDER && npm install medium-zoom highlight.js
 ```
 
 **`.vitepress/theme/index.css`** — create if it doesn't exist, otherwise append:
@@ -753,7 +793,7 @@ Add `docs-manifest.json` to `.vitepress/` entry in `.gitignore`.
 
 ```
 Generated X pages (Y user-facing, Z developer).
-Created N placeholder screenshots — run /vitepress:docs screenshot when ready to capture real images.
+Created N placeholder screenshots — run /vitedocs:screenshot when ready to capture real images.
 Filled M of P gaps — X remaining gap comments left in files for manual review.
 ```
 
@@ -785,8 +825,8 @@ const OUTPUT = 'FILL_IN_OUTPUT_PATH';
 const scanlines = [];
 for (let y = 0; y < H; y++) {
   const row = Buffer.alloc(1 + W * 3);
-  row[0] = 0;        // filter type: None
-  row.fill(0x88, 1); // grey RGB pixels
+  row[0] = 0;
+  row.fill(0x88, 1);
   scanlines.push(row);
 }
 const raw = Buffer.concat(scanlines);
@@ -813,7 +853,7 @@ function makeChunk(type, data) {
 const sig = Buffer.from([137,80,78,71,13,10,26,10]);
 const ihdr = Buffer.alloc(13);
 ihdr.writeUInt32BE(W, 0); ihdr.writeUInt32BE(H, 4);
-ihdr[8] = 8; ihdr[9] = 2; // 8-bit RGB
+ihdr[8] = 8; ihdr[9] = 2;
 
 mkdirSync(dirname(OUTPUT), { recursive: true });
 writeFileSync(OUTPUT, Buffer.concat([
@@ -896,7 +936,7 @@ import { chromium } from '/opt/homebrew/lib/node_modules/playwright/index.mjs';
 
 **⛔ Credential rule — NEVER write credentials to any file.** Do not write them to a script file, `.env`, the manifest, or anywhere on disk. All Playwright scripts run as inline bash heredocs — credentials are passed directly as inline values to `page.fill()` calls within the heredoc and exist only in memory for the duration of the command. If Playwright needs credentials in a reusable way, use a saved storage state file — but prompt the user for credentials fresh each time rather than caching them.
 
-**For pages requiring auth:** if credentials were provided, drive a login flow before navigating to the target URL. If no credentials were given, skip auth-gated pages and list them in the final summary so the user can run screenshot mode again with credentials.
+**For pages requiring auth:** if credentials were provided, drive a login flow before navigating to the target URL. If no credentials were given, skip auth-gated pages and list them in the final summary so the user can run `/vitedocs:screenshot` again with credentials.
 
 **Standard capture script template:**
 
@@ -916,9 +956,7 @@ SCRIPT
 
 Adjust `SETTLE_MS` based on stack type: WordPress/non-SPA → `500`, Next.js/SPA → `2000`–`4000`.
 
-Never write the script to a file — always use the heredoc form above. This applies to auth flows too: inline all credential usage directly in the heredoc, never in a file.
-
-After each capture, display the image inline with the Read tool so the user can verify it before moving on.
+Never write the script to a file — always use the heredoc form above.
 
 ### Step 4 — Rewrite prose around captured images
 
@@ -938,7 +976,7 @@ Captured X of Y screenshots.
 
 Rewrote prose in X doc pages.
 
-Run /vitepress:docs sync after future code changes to keep docs current.
+Run /vitedocs:sync after future code changes to keep docs current.
 ```
 
 ---
@@ -1021,7 +1059,276 @@ Update `lastSynced` and `syncHash` for all updated pages. Update the top-level `
 ```
 Updated X of N drifted pages.
   X gap comments added for manual review.
-  Y screenshots flagged for recapture — run /vitepress:docs screenshot when ready.
+  Y screenshots flagged for recapture — run /vitedocs:screenshot when ready.
+```
+
+---
+
+## Mode: brand
+
+### Step 1 — Locate docs paths
+
+Check the manifest(s) to find all configured docs folders. If no manifest exists, scan for `.vitepress/config.mjs` files across the known focus paths. Present what was found so the user can confirm before proceeding.
+
+### Step 2 — Shared or per-path branding
+
+If more than one docs path is found, ask:
+
+- header: "Branding scope"
+- question: "How should branding be applied across your docs?"
+- options:
+  - "Same brand across all docs"
+  - "Different brand per path — I'll configure each one separately"
+
+If per-path: complete all brand questions for path 1 before moving to path 2 — never ask about two paths simultaneously.
+
+### Step 3 — Brand questions
+
+Ask these once (shared) or once per path (per-path). Always label the header with the path name when in per-path mode so the user knows which repo they're configuring.
+
+**B-Q1 — Primary brand color** (plain text): Ask — "What is the primary brand color? (hex, e.g. `#E63946`). This becomes the link, button, and accent color throughout the docs."
+
+From this single hex value, derive the full VitePress brand palette automatically:
+- `--vp-c-brand-1`: the base hex
+- `--vp-c-brand-2`: 15% lighter
+- `--vp-c-brand-3`: 30% lighter
+- `--vp-c-brand-soft`: the hex at 12% opacity (for backgrounds)
+
+Also derive dark mode variants — slightly brighter versions of each to account for dark backgrounds. Present the derived palette to the user before writing anything.
+
+**B-Q2 — Logo:**
+- header: "Logo"
+- question: "Do you have a logo to use in the docs nav?"
+- options:
+  - "Yes — I'll provide the path to the file"
+  - "Text only — use the site title"
+  - "Skip for now"
+
+If yes: ask as plain text — "What is the path to the logo file? (SVG or PNG recommended, e.g. `public/logo.svg`)"
+
+**B-Q3 — Favicon:**
+- header: "Favicon"
+- question: "Do you have a favicon?"
+- options:
+  - "Yes — I'll provide the path"
+  - "Use the logo as favicon"
+  - "Skip for now"
+
+If yes: ask as plain text — "Path to favicon? (e.g. `public/favicon.ico` or `public/favicon.svg`)"
+
+**B-Q4 — Font:**
+- header: "Font"
+- question: "What font should the docs use?"
+- options:
+  - "VitePress default (Inter)"
+  - "System font stack (no external load)"
+  - "Google Font — I'll tell you which"
+  - "Custom — I'll provide the CSS import"
+
+If Google Font: ask as plain text — "Which Google Font family? (e.g. `Outfit`, `DM Sans`)"
+If custom: ask as plain text — "Paste your @import or @font-face CSS."
+
+**B-Q5 — Dark mode:**
+- header: "Dark mode"
+- question: "How should dark mode colors work?"
+- options:
+  - "Auto-derive from brand color (recommended)"
+  - "I want to set a custom dark mode accent color"
+  - "Use VitePress default dark mode"
+
+If custom: ask as plain text — "What hex color for dark mode accent?"
+
+### Step 4 — Preview palette
+
+Before writing any files, present the full derived palette as a table:
+
+```
+Light mode
+  --vp-c-brand-1:    #E63946
+  --vp-c-brand-2:    #EB5E6A
+  --vp-c-brand-3:    #F28B93
+  --vp-c-brand-soft: #E6394620
+
+Dark mode
+  --vp-c-brand-1:    #F05A64
+  --vp-c-brand-2:    #F47980
+  --vp-c-brand-3:    #F7A0A5
+  --vp-c-brand-soft: #F05A6420
+```
+
+Then ask:
+
+- header: "Palette"
+- question: "Does this palette look right?"
+- options:
+  - "Yes — apply it"
+  - "Adjust the base color — I'll give you a new hex"
+  - "Manually tweak individual values"
+
+If adjust: take the new hex and re-derive. If manual: ask as plain text for each value to change.
+
+### Step 5 — Write brand files
+
+For each docs path being branded:
+
+**`.vitepress/theme/index.css`** — append the brand variables block. Do not remove existing entries — only add or update the brand vars:
+
+```css
+:root {
+  --vp-c-brand-1: HEX1;
+  --vp-c-brand-2: HEX2;
+  --vp-c-brand-3: HEX3;
+  --vp-c-brand-soft: HEXSOFT;
+  /* FONT_VARS if custom font selected */
+}
+
+.dark {
+  --vp-c-brand-1: DARK_HEX1;
+  --vp-c-brand-2: DARK_HEX2;
+  --vp-c-brand-3: DARK_HEX3;
+  --vp-c-brand-soft: DARK_HEXSOFT;
+}
+```
+
+If a Google Font was selected, add the `@import` at the top of the CSS file and set `--vp-font-family-base`.
+
+**`.vitepress/config.mjs`** — add to `themeConfig`:
+- `logo` field if a logo was provided
+- `favicon` via `head` entry if a favicon was provided
+
+Read the existing config before editing. Make only targeted additions — do not rewrite unrelated sections.
+
+### Step 6 — Summary
+
+```
+Branded X docs path(s).
+
+Files updated:
+  PATH/.vitepress/theme/index.css  — brand palette + font
+  PATH/.vitepress/config.mjs       — logo, favicon
+
+Run the local dev server to preview: npm run dev
+```
+
+---
+
+## Mode: update
+
+Retrofits an existing VitePress docs setup with the latest components, dependencies, and theme wiring. Does not re-run setup or regenerate pages.
+
+### Step 1 — Locate docs paths
+
+Scan the current working directory and any known focus paths for `.vitepress/config.mjs` (or `.ts`) files. List what was found and ask the user to confirm which paths to update.
+
+### Step 2 — Inventory current state
+
+For each confirmed docs path, check what is already present:
+
+- `.vitepress/components/ApiEndpoint.vue` — exists?
+- `.vitepress/theme/index.js` — exists? includes `medium-zoom`? includes `ApiEndpoint`?
+- `.vitepress/theme/index.css` — exists? includes `.medium-zoom-overlay` z-index rules?
+- `package.json` — are `medium-zoom` and `highlight.js` listed in dependencies?
+
+Report findings as a checklist:
+```
+Path: docs/
+  [x] ApiEndpoint.vue — found (needs update)
+  [ ] medium-zoom installed
+  [x] highlight.js installed
+  [x] theme/index.js — found (missing medium-zoom wiring)
+  [x] theme/index.css — found (missing z-index rules)
+```
+
+Then ask:
+
+- header: "Update"
+- question: "What would you like to update?"
+- options:
+  - "Everything that's missing or outdated"
+  - "Let me choose item by item"
+
+### Step 3 — Gather inputs (only if needed)
+
+If `ApiEndpoint.vue` is being written or updated and no existing `apiBase` is in the VitePress config, ask:
+
+**U-Q1 — API base URL** (plain text): "What is the API base URL? (e.g. `https://api.example.com/wp-json/my-plugin/v1`)"
+
+**U-Q2 — Code sample tabs:**
+- header: "Code tabs"
+- question: "Which code sample tabs should the ApiEndpoint component show?"
+- options:
+  - "Fetch + cURL (default)"
+  - "Fetch + cURL + PHP"
+  - "Fetch + cURL + Python"
+  - "Fetch + cURL + Axios"
+  - "All of the above"
+  - "Custom — I'll list them"
+
+Skip U-Q1 and U-Q2 if `apiBase` already exists in `.vitepress/config.mjs` `themeConfig` — infer `apiBase` and existing tabs from the config and the current `ApiEndpoint.vue`.
+
+### Step 4 — Apply updates
+
+Apply only the items selected (or all missing/outdated items if "Everything" was chosen). Always read existing files before editing — never overwrite unrelated content.
+
+**`ApiEndpoint.vue`** — write the full component from the template in generate Step 6, substituting the correct tab list. If the file already exists, replace it entirely (it is a generated component, not hand-edited).
+
+**`medium-zoom` + `highlight.js`** — if either is missing from `package.json` dependencies, run:
+```bash
+cd DOCS_FOLDER && npm install medium-zoom highlight.js
+```
+
+**`.vitepress/theme/index.css`** — if `.medium-zoom-overlay` z-index block is missing, append:
+```css
+.medium-zoom-overlay {
+  z-index: 100;
+}
+
+.medium-zoom-image--opened {
+  z-index: 101;
+}
+```
+Do not remove or overwrite existing entries.
+
+**`.vitepress/theme/index.js`** — merge only what is missing:
+- If `medium-zoom` wiring is absent, add the `onMounted`/`watch` setup block
+- If `ApiEndpoint` registration is absent (and `apiBase` is configured), add the import and `app.component()` call
+- Never remove existing registrations or setup logic
+
+Reference template for the full correct state:
+```js
+import DefaultTheme from 'vitepress/theme'
+import { onMounted, watch, nextTick } from 'vue'
+import { useRoute } from 'vitepress'
+import mediumZoom from 'medium-zoom'
+import './index.css'
+import ApiEndpoint from '../components/ApiEndpoint.vue'
+
+export default {
+  extends: DefaultTheme,
+  setup() {
+    const route = useRoute()
+    const initZoom = () => mediumZoom('.main img', { background: 'var(--vp-c-bg)' })
+    onMounted(initZoom)
+    watch(() => route.path, () => nextTick(initZoom))
+  },
+  enhanceApp({ app }) {
+    app.component('ApiEndpoint', ApiEndpoint)
+  }
+}
+```
+
+**`.vitepress/config.mjs`** — if `apiBase` was collected and is not already in `themeConfig`, add it.
+
+### Step 5 — Summary
+
+```
+Updated X of Y docs path(s).
+
+Changes applied:
+  PATH/.vitepress/components/ApiEndpoint.vue  — written
+  PATH/.vitepress/theme/index.js              — merged medium-zoom + ApiEndpoint
+  PATH/.vitepress/theme/index.css             — added z-index rules
+  PATH/package.json                           — installed medium-zoom, highlight.js
 ```
 
 ---

package/install.js

@@ -1,17 +1,21 @@
 #!/usr/bin/env node
-import { mkdirSync, copyFileSync } from 'fs';
+import { mkdirSync, copyFileSync, readdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-const skillName = 'vitepress-docs';
-const dest = join(homedir(), '.claude', 'skills', skillName);
+const src = join(__dirname, 'commands', 'vitedocs');
+const dest = join(homedir(), '.claude', 'commands', 'vitedocs');
 
 mkdirSync(dest, { recursive: true });
-copyFileSync(join(__dirname, 'skill', 'SKILL.md'), join(dest, 'SKILL.md'));
+
+const files = readdirSync(src).filter(f => f.endsWith('.md'));
+for (const file of files) {
+  copyFileSync(join(src, file), join(dest, file));
+}
 
 console.log(`✓ Installed @iamdangavin/claude-skill-vitepress-docs`);
-console.log(`  → ${dest}/SKILL.md`);
-console.log(`  Invoke with: /vitepress-docs in Claude Code`);
+console.log(`  → ${dest}/`);
+console.log(`  Invoke with: /vitedocs:init in Claude Code`);

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@iamdangavin/claude-skill-vitepress-docs",
-  "version": "1.9.0",
-  "description": "Installs the vitepress:docs Claude Code skill — VitePress docs setup, generation, screenshots, and sync.",
+  "version": "3.0.0",
+  "description": "Installs the vitedocs: Claude Code skill suite — VitePress docs setup, generate, screenshot, sync, brand, and update.",
   "type": "module",
   "bin": {
     "claude-skill-vitepress-docs": "./install.js"
   },
   "files": [
     "install.js",
-    "skill/"
+    "commands/"
   ],
   "keywords": [
     "claude",