claude-skill-vitepress-docs

A 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

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
• Playwright (for /vitedocs:capture — install with npx playwright install)
• A GitHub repo with GitHub Pages enabled (for deployment and video hosting)