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

package/package.json

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

package/skill/SKILL.md

@@ -414,6 +414,34 @@ If "Somewhere else": ask as plain text — "What path should I use? (Full path o
 
 Always show the full resolved path — never use abstract terms like "project root."
 
+**Q1b — API base URL** (only if developer or both selected): Scan for API endpoints first — look for REST API routes, WP REST API extensions, Next.js API routes, Express routers, etc. If any are found, ask:
+
+- header: "API base URL"
+- question: "I found API endpoints in the codebase. What is the base URL for your API? This is used to generate live code samples in the docs."
+- options:
+  - "Same as the local dev URL already provided"
+  - "Different URL — I'll type it"
+  - "Skip — I don't want code samples"
+
+If different: ask as plain text — "What is the API base URL? (e.g. `http://localhost:8888/wp-json` or `https://api.mysite.com`)"
+
+Then ask:
+
+- header: "Code sample tabs"
+- question: "Which code sample types should the API endpoint component show?"
+- options:
+  - "Fetch + cURL (default)"
+  - "Fetch only"
+  - "cURL only"
+  - "Fetch + cURL + PHP"
+  - "Custom — I'll tell you which"
+
+If custom: ask as plain text — "Which languages or methods? (e.g. Fetch, cURL, PHP, Python, Axios)"
+
+Store the selected tabs — they determine which tab options are rendered in the `ApiEndpoint` component and which code samples are generated per endpoint.
+
+Store `apiBase` and `tabs` — both used in VitePress config and the `ApiEndpoint` component.
+
 **Q5 — Skip anything:**
 - header: "Exclusions"
 - question: "Anything to exclude from analysis? (node_modules, dist, .git, .next, coverage are always skipped.)"
@@ -483,6 +511,17 @@ Write pages one at a time. For each page:
    ```
    Then generate the placeholder PNG (see **Placeholder generation** below).
 
+5. For any page documenting API endpoints (REST routes, WP REST API extensions, etc.), use the `ApiEndpoint` component instead of plain code blocks — but only if `apiBase` was collected in Q1b. Use it like this:
+   ```md
+   <ApiEndpoint
+     method="GET"
+     path="/wp-json/alabama-news/v1/sources"
+     auth="none"
+     :response="{ sources: ['AP', 'Reuters'] }"
+   />
+   ```
+   Populate `method`, `path`, `auth`, `body`, and `response` from what you read in the source files. If a request body or response shape is unclear, leave it as a gap comment.
+
 Do not stop to ask gap questions mid-page. Keep writing and accumulate all gaps.
 
 ### Step 5 — Gap review
@@ -500,10 +539,187 @@ the correct information. Can you fill these in?
 
 Go back and fill in the answers the user provides.
 
-### Step 6 — Update VitePress config sidebar
+### Step 6 — Install VitePress components
+
+If `apiBase` was collected in Q1b, write the following files before updating the config.
+
+**`.vitepress/components/ApiEndpoint.vue`** — write this file exactly, substituting `TABS` with the selected tab labels (e.g. `['Fetch', 'cURL']`) and adding sample generators for any additional tabs beyond Fetch and cURL:
+
+```vue
+<template>
+  <div class="api-ep">
+    <div class="api-ep__header">
+      <div class="api-ep__badge">
+        <span class="api-ep__method" :class="`api-ep__method--${method.toLowerCase()}`">{{ method }}</span>
+        <code class="api-ep__path">{{ path }}</code>
+      </div>
+      <span class="api-ep__auth">{{ authLabel }}</span>
+    </div>
+    <div class="api-ep__body">
+      <div class="api-ep__tabs">
+        <button
+          v-for="tab in tabs"
+          :key="tab"
+          class="api-ep__tab"
+          :class="{ 'api-ep__tab--active': activeTab === tab }"
+          @click="activeTab = tab"
+        >{{ tab }}</button>
+      </div>
+      <pre class="api-ep__code"><code>{{ currentSample }}</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>
+      </template>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref, computed } from 'vue'
+import { useData } from 'vitepress'
+
+const props = defineProps({
+  method: { type: String, required: true },
+  path: { type: String, required: true },
+  auth: { type: String, default: 'authenticated' },
+  body: { type: Object, default: null },
+  response: { type: Object, default: null },
+  formData: { type: Boolean, default: false },
+})
+
+const { theme } = useData()
+const baseUrl = computed(() => theme.value.apiBase ?? '')
+
+const authLabel = computed(() => ({
+  'authenticated': 'Auth required',
+  'admin:manage': 'Admin only',
+  'self': 'Authenticated (self)',
+  'none': 'Unauthenticated',
+}[props.auth] ?? props.auth))
+
+const tabs = TABS  // substituted from Q1b answer
+const activeTab = ref(tabs[0])
+
+const fetchSample = computed(() => {
+  const url = `${baseUrl.value}${props.path}`
+  if (props.method === 'GET') {
+    return `const res = await fetch('${url}', {\n  credentials: 'include'\n})\nconst data = await res.json()`
+  }
+  if (props.formData) {
+    return `const form = new FormData()\n// append fields to form...\n\nconst res = await fetch('${url}', {\n  method: 'POST',\n  credentials: 'include',\n  body: form\n})\nconst data = await res.json()`
+  }
+  const bodyStr = props.body ? JSON.stringify(props.body, null, 2) : '{}'
+  return `const res = await fetch('${url}', {\n  method: '${props.method}',\n  headers: { 'Content-Type': 'application/json' },\n  credentials: 'include',\n  body: JSON.stringify(${bodyStr})\n})\nconst data = await res.json()`
+})
+
+const curlSample = computed(() => {
+  const url = `${baseUrl.value}${props.path}`
+  if (props.method === 'GET') {
+    return `curl '${url}' \\\n  -H 'Cookie: <session-cookie>'`
+  }
+  if (props.formData) {
+    return `curl -X POST '${url}' \\\n  -H 'Cookie: <session-cookie>' \\\n  -F 'field=value'`
+  }
+  const bodyStr = props.body ? JSON.stringify(props.body, null, 2) : '{}'
+  return `curl -X ${props.method} '${url}' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Cookie: <session-cookie>' \\\n  -d '${bodyStr}'`
+})
+
+// Add additional sample computed properties here for PHP, Python, Axios etc if selected in Q1b
+
+const currentSample = computed(() => {
+  if (activeTab.value === 'Fetch') return fetchSample.value
+  if (activeTab.value === 'cURL') return curlSample.value
+  return ''
+})
+
+const formattedResponse = computed(() =>
+  props.response ? JSON.stringify(props.response, null, 2) : ''
+)
+</script>
+
+<style scoped>
+.api-ep { border: 1px solid var(--vp-c-divider); border-radius: 8px; margin: 1.5rem 0 2.5rem; overflow: hidden; }
+.api-ep__header { display: flex; align-items: center; justify-content: space-between; gap: 12px; padding: 10px 16px; background: var(--vp-c-bg-soft); border-bottom: 1px solid var(--vp-c-divider); }
+.api-ep__badge { display: flex; align-items: center; gap: 10px; min-width: 0; }
+.api-ep__method { display: inline-flex; align-items: center; font-size: 0.65rem; font-weight: 700; letter-spacing: 0.06em; padding: 2px 7px; border-radius: 4px; flex-shrink: 0; }
+.api-ep__method--get { background: var(--vp-c-green-soft); color: var(--vp-c-green-1); }
+.api-ep__method--post { background: var(--vp-c-brand-soft); color: var(--vp-c-brand-1); }
+.api-ep__method--put { background: var(--vp-c-yellow-soft); color: var(--vp-c-yellow-1); }
+.api-ep__method--delete { background: var(--vp-c-danger-soft); color: var(--vp-c-danger-1); }
+.api-ep__path { font-family: var(--vp-font-family-mono); font-size: 0.85rem; color: var(--vp-c-text-1); background: none; padding: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.api-ep__auth { font-size: 0.7rem; font-weight: 500; color: var(--vp-c-text-3); flex-shrink: 0; white-space: nowrap; }
+.api-ep__body { padding: 16px; background: var(--vp-c-bg-soft); display: flex; flex-direction: column; gap: 8px; }
+.api-ep__tabs { display: flex; gap: 4px; margin-bottom: 2px; }
+.api-ep__tab { font-size: 0.75rem; font-weight: 500; padding: 3px 10px; border-radius: 4px; border: 1px solid transparent; background: transparent; color: var(--vp-c-text-2); cursor: pointer; transition: all 0.15s; }
+.api-ep__tab:hover { color: var(--vp-c-text-1); background: var(--vp-c-default-soft); }
+.api-ep__tab--active { border-color: var(--vp-c-divider); background: var(--vp-c-bg); color: var(--vp-c-text-1); }
+.api-ep__code { margin: 0; padding: 12px; background: var(--vp-c-bg); border-radius: 6px; overflow-x: auto; font-family: var(--vp-font-family-mono); font-size: 0.72rem; line-height: 1.65; color: var(--vp-c-text-1); }
+.api-ep__code code { background: none; padding: 0; font-size: inherit; color: inherit; }
+.api-ep__note { font-size: 0.7rem; color: var(--vp-c-text-3); margin: 0; line-height: 1.5; }
+.api-ep__section-label { font-size: 0.68rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.06em; color: var(--vp-c-text-3); margin-top: 4px; }
+</style>
+```
+
+**Install `medium-zoom`** in the docs folder:
+
+```bash
+cd DOCS_FOLDER && npm install medium-zoom
+```
+
+**`.vitepress/theme/index.css`** — create if it doesn't exist, otherwise append:
+
+```css
+.medium-zoom-overlay {
+  z-index: 20;
+}
+
+.medium-zoom-image {
+  z-index: 21;
+}
+```
+
+**`.vitepress/theme/index.js`** — create if it doesn't exist, otherwise merge into existing. This template includes both `ApiEndpoint` registration and medium-zoom. If `apiBase` was not collected, omit the `ApiEndpoint` lines:
+
+```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)
+  }
+}
+```
+
+If the file already exists, merge only the missing pieces — do not overwrite other registrations or setup logic.
+
+### Step 6b — Update VitePress config sidebar
 
 Read the existing `.vitepress/config.mjs` (or `.ts`) and update the `sidebar` and `nav` to include all newly generated pages. Edit the config in place — do not rewrite unrelated sections.
 
+If `apiBase` was collected, also add it to `themeConfig`:
+
+```js
+themeConfig: {
+  apiBase: 'API_BASE_URL',
+  // ...existing themeConfig
+}
+```
+
 ### Step 7 — Write the manifest
 
 Write `.vitepress/docs-manifest.json` capturing all pages, their source file mappings, image placeholder status, and a `syncHash` (SHA of source file contents at generation time — use a simple string hash if needed).
@@ -655,22 +871,29 @@ Use Playwright via Homebrew for all captures:
 import { chromium } from '/opt/homebrew/lib/node_modules/playwright/index.mjs';
 ```
 
-**⛔ Credential rule — NEVER write credentials to any file.** Do not write them to the capture script, a `.env` file, the manifest, a temp file, or anywhere else. Use them only as inline values passed directly to `page.fill()` calls in the script held in memory. Delete the script immediately after running it (`rm /tmp/screenshot.mjs`). 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.
+**⛔ 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.
 
 **Standard capture script template:**
-```js
+
+Run inline via bash heredoc — no file is ever written to disk:
+
+```bash
+node --input-type=module << 'SCRIPT'
 import { chromium } from '/opt/homebrew/lib/node_modules/playwright/index.mjs';
 const browser = await chromium.launch({ channel: 'chrome', args: ['--no-sandbox'] });
 const page = await browser.newPage({ viewport: { width: 1440, height: 900 } });
 await page.goto('BASE_URL + captureUrl', { waitUntil: 'load', timeout: 60000 });
-await page.waitForTimeout(2000); // settle time for SPAs
+await page.waitForTimeout(SETTLE_MS);
 await page.screenshot({ path: 'OUTPUT_PATH', fullPage: false });
 await browser.close();
+SCRIPT
 ```
 
-Adjust settle time based on stack type. For WordPress/non-SPA sites use 500ms. For Next.js/SPA use 2000–4000ms.
+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.