@iamdangavin/claude-skill-vitepress-docs 1.8.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamdangavin/claude-skill-vitepress-docs",
-  "version": "1.8.0",
+  "version": "2.1.0",
   "description": "Installs the vitepress:docs Claude Code skill — VitePress docs setup, generation, screenshots, and sync.",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -23,6 +23,8 @@ Four modes for full VitePress documentation lifecycle. If no mode is given as an
   - "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 and dependencies"
 
 ---
 
@@ -105,6 +107,29 @@ If "Somewhere else": ask as plain text — "What path should I use? (Full path o
 
 If custom domain: ask as plain text — "What is the domain? (e.g. `docs.myapp.com`)"
 
+**Q4b — Search engine visibility:**
+- header: "Search visibility"
+- question: "Should these docs be visible to search engines and bots?"
+- options:
+  - "Yes — index these docs publicly"
+  - "No — block all search engines and bots"
+
+If "No": add the following to the VitePress config's `head` array and write a `robots.txt` to the public folder:
+
+`head` entry in `config.mjs`:
+```js
+head: [
+  ['meta', { name: 'robots', content: 'noindex, nofollow' }],
+]
+```
+If a `head` array already exists in the config, append to it — do not replace it.
+
+`DOCS_FOLDER/public/robots.txt`:
+```
+User-agent: *
+Disallow: /
+```
+
 **Q5 — Deploy trigger:**
 - header: "Deploy trigger"
 - question: "When should docs deploy?"
@@ -565,13 +590,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>
@@ -580,6 +605,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 },
@@ -635,9 +673,33 @@ const currentSample = computed(() => {
   return ''
 })
 
+// Map tab names to highlight.js language identifiers
+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>
@@ -663,21 +725,21 @@ 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:
 
 ```css
 .medium-zoom-overlay {
-  z-index: 20;
+  z-index: 100;
 }
 
-.medium-zoom-image {
-  z-index: 21;
+.medium-zoom-image--opened {
+  z-index: 101;
 }
 ```
 
@@ -1003,6 +1065,284 @@ Updated X of N drifted pages.
 
 ---
 
+## 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 from this skill. 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 upgrade.
+
+### Step 2 — Inventory current state
+
+For each confirmed docs path, check what is already present:
+
+- `.vitepress/components/ApiEndpoint.vue` — exists? version detectable?
+- `.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 upgrades
+
+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
+
+Use this as the reference template for the full correct state of `index.js`:
+```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:
+```js
+themeConfig: {
+  apiBase: 'API_BASE_URL',
+  // ...existing themeConfig
+}
+```
+
+### Step 5 — Summary
+
+```
+Upgraded X of Y docs path(s).
+
+Changes applied:
+  PATH/.vitepress/components/ApiEndpoint.vue  — written (tabs: Fetch, cURL, PHP)
+  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
+
+No changes needed:
+  PATH/.vitepress/config.mjs                  — apiBase already present
+```
+
+---
+
 ## Notes
 
 - Never write the GitHub Actions workflow inside the docs folder — it goes in `.github/workflows/` at the repo root.