# claude-skill-vitepress-docs

A [Claude Code](https://claude.ai/claude-code) skill suite for creating and maintaining VitePress documentation for any project. Covers the full docs lifecycle — from initial setup through writing, capturing screenshots and videos, keeping docs in sync with code changes, and configuring visual branding.

## Installation

```bash
npx @iamdangavin/claude-skill-vitepress-docs
```

This installs the `vitedocs:` command suite into `~/.claude/commands/vitedocs/`. Commands are then available in any Claude Code session.

## Commands

### `/vitedocs:init`

Entry point. Asks which mode you need and tells you which command to run next. Use this if you're not sure where to start.

---

### `/vitedocs:setup`

Wire up VitePress and GitHub Actions for GitHub Pages deployment.

- Scaffolds the VitePress config, package.json, and directory structure inside your chosen docs folder
- Writes a GitHub Actions workflow (`.github/workflows/deploy-docs.yml`) that builds and deploys to GitHub Pages on push
- Adds `node_modules` and `.vitepress/cache` to `.gitignore`
- Outputs the expected deploy URL and a next-steps checklist

**Next:** `/vitedocs:generate`

---

### `/vitedocs:generate`

Analyze the codebase and write documentation pages.

- Auto-detects the tech stack (Next.js, WordPress, Node, static, etc.) before asking any questions
- Supports user-facing guides, developer reference docs, or both
- Proposes a doc structure outline and confirms before writing anything
- Identifies 3–6 home page feature highlights drawn from the actual codebase
- Writes all pages with real content — gaps are marked with `<!-- GAP: ... -->` comments rather than stopping to ask
- Inserts image placeholders and records them in `.vitepress/docs-manifest.json` for capture later
- Suggests video captures (via `VideoDemo`) for interactive flows and screenshots for static UI states
- Installs and registers custom VitePress components: `ApiEndpoint`, `VideoDemo`, medium-zoom
- Generates API endpoint docs using the `ApiEndpoint` component when REST routes are found
- Includes color chips (inline swatches) in any table that references color values

**Next:** `/vitedocs:capture` (if placeholder images were created)

---

### `/vitedocs:capture`

Capture screenshots and record interaction videos for docs pages.

- Reads `.vitepress/docs-manifest.json` to find all pending captures
- Batches all screenshots into a single script (one approval covers the full set)
- Records `.webm` interaction videos using Playwright with step-by-step captions
- Generates `.vtt` caption files (committed to git) synced to video timestamps
- Shows a custom cursor overlay during video recordings for visibility
- Hides the Next.js Turbopack dev tools badge (`#devtools-indicator`) in all captures
- Supports local dev servers (Node or non-Node) and deployed URLs
- Handles auth-gated screens — credentials are used only in-session and never written to any file
- Videos are uploaded to GitHub Releases (tagged `docs-media`) to keep binary files out of git
- Rewrites surrounding prose to match what was actually captured

**Next:** `/vitedocs:sync`

---

### `/vitedocs:sync`

Detect code drift and update docs that are out of date.

- Hashes source files referenced in the manifest and compares against `syncHash` values from last sync
- Reports which pages have drifted and which are current
- Rewrites only the sections that changed — does not regenerate entire pages
- Flags screenshots that may need recapture after content changes
- Confirms each proposed update before writing

**Next:** `/vitedocs:capture` (if screenshots were flagged for recapture)

---

### `/vitedocs:brand`

Configure colors, fonts, logo, and favicon for VitePress docs.

- Derives a full VitePress brand palette (4 tokens, light + dark) from a single hex color
- Previews the derived palette as a table with inline color chips before writing anything
- Supports Google Fonts, custom CSS imports, or the VitePress default (Inter)
- Writes brand variables to `.vitepress/theme/index.css` and logo/favicon to `config.mjs`
- Can apply shared branding across all docs paths or different branding per path

**Next:** `/vitedocs:capture` or `/vitedocs:sync`

---

### `/vitedocs:update`

Retrofit an existing VitePress docs setup with the latest components and dependencies.

- Writes or overwrites `ApiEndpoint.vue` and `VideoDemo.vue` to the latest versions
- Merges medium-zoom setup and component registrations into `.vitepress/theme/index.js`
- Adds required z-index CSS rules to `index.css`
- Installs `medium-zoom` and `highlight.js` if not already present
- Reads existing files before editing — never rewrites unrelated config sections

**Next:** `/vitedocs:capture` or `/vitedocs:sync`

---

## How the commands fit together

```
setup → generate → capture → sync (repeat as code changes)
                 ↘ brand (anytime)
                 ↘ update (when upgrading the skill)
```

## Manifest

All modes read and write `.vitepress/docs-manifest.json`. This file tracks page-to-source mappings, image placeholder status, sync hashes, and video metadata. It is local-only and should be added to `.gitignore`.

## Requirements

- [Claude Code](https://claude.ai/claude-code)
- [Playwright](https://playwright.dev/) (for `/vitedocs:capture` — install with `npx playwright install`)
- A GitHub repo with GitHub Pages enabled (for deployment and video hosting)