@iamdangavin/claude-skill-vitepress-docs 1.4.0 → 1.6.0

package/package.json

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

package/skill/SKILL.md

@@ -76,6 +76,8 @@ Add this line if not already present:
 
 Use AskUserQuestion for each choice below. For freeform text inputs (repo URL, domain name, docs path) ask as plain text immediately after the relevant choice is made.
 
+**Multiple focus paths:** if more than one path was established in Step 0, ask Q2 through Q6 once per path — fully completing all questions for the first path before starting the second. Never present questions for two paths at the same time.
+
 **Q1 — VitePress status:**
 - header: "VitePress"
 - question: "Is VitePress already installed in this project?"
@@ -83,7 +85,14 @@ Use AskUserQuestion for each choice below. For freeform text inputs (repo URL, d
   - "Already installed"
   - "Starting from scratch"
 
-**Q2 — Docs folder** (plain text): Ask — "Where do the docs live (or where should they go)? e.g. `docs/` at project root, or the repo root itself."
+**Q2 — Docs folder:**
+- header: "Docs location"
+- question: "Where should the docs folder be created? I found your repo at `[GIT_ROOT_PATH]`."
+- options:
+  - "Here → `[GIT_ROOT_PATH]/docs/`"
+  - "Somewhere else — I'll type the path"
+
+If "Somewhere else": ask as plain text — "What path should I use? (Full path or relative to `[GIT_ROOT_PATH]`)"
 
 **Q3 — GitHub repo** (plain text): Ask — "What is the GitHub repo? (full URL or `owner/repo`)"
 
@@ -385,7 +394,53 @@ This matters because the GitHub Actions workflow file must go in `.github/workfl
 
 **Q3 — Codebase root** (plain text): Ask — "Where is the codebase root? (Press enter to use the current directory.)" — **Skip for WordPress; already established by WP-Q6.**
 
-**Q4 — Docs output** (plain text): Ask — "Where should docs be written? (Default: `docs/` inside [FOCUS_PATH].)" — For WordPress, default to `docs/` inside the theme/plugin folder from WP-Q6, not the WP install root.
+**Q4 — Docs output:** Before asking, check whether `setup` has already been run by looking for `.vitepress/config.mjs` anywhere inside the focus path:
+
+```bash
+find FOCUS_PATH -name "config.mjs" -path "*/.vitepress/*" 2>/dev/null
+```
+
+**If found:** docs location is already established — skip this question, infer the docs folder from the found path, and tell the user: "I found an existing VitePress config at `[PATH]` — using that as the docs folder."
+
+**If not found:** ask:
+
+- header: "Docs location"
+- question: "Where should the docs folder be created? I found your repo at `[GIT_ROOT_PATH]`."
+- options:
+  - "Here → `[GIT_ROOT_PATH]/docs/`"
+  - "Somewhere else — I'll type the path"
+
+If "Somewhere else": ask as plain text — "What path should I use? (Full path or relative to `[GIT_ROOT_PATH]`)"
+
+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"
@@ -456,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
@@ -473,10 +539,159 @@ 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>
+```
+
+**`.vitepress/theme/index.js`** — create if it doesn't exist, otherwise merge into existing:
+
+```js
+import DefaultTheme from 'vitepress/theme'
+import ApiEndpoint from '../components/ApiEndpoint.vue'
+
+export default {
+  extends: DefaultTheme,
+  enhanceApp({ app }) {
+    app.component('ApiEndpoint', ApiEndpoint)
+  }
+}
+```
+
+If the file already exists, add only the import and `app.component()` line — do not overwrite other registrations.
+
+### 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).