Implement docs-md-ghpages: Documentation for GitHub Pages

[vredchenko]

Summary

The docs-md-ghpages plugin manages project documentation as markdown/MDX files in a docs/ directory, published to GitHub Pages via static site generators. This is valuable because setting up a docs site involves choosing an SSG, configuring it, writing a GitHub Actions workflow, and keeping docs in sync with code — all boilerplate the plugin handles.

Original Intent

Keep project documentation in docs/ directory under version control as md or mdx, publish to GitHub Pages or a locally run static web site, generating from docs/ content, reference from README, remember to update as codebase changes. Claude Code configured to reference these for context and project awareness.

Commands

/docs:generate

Purpose: Generate or update project documentation in docs/ directory.

Behavior:

1. Check for existing docs setup:

   • docs/ directory with existing content
   • SSG config: mkdocs.yml, docusaurus.config.js, .vitepress/config.ts
   • If exists → enter update mode (analyze what's changed, suggest new docs)

2. If no docs exist, ask user to choose SSG:

   SSG	Best For	Language	Config
   MkDocs Material (recommended)	Technical docs, API references	Python	mkdocs.yml
   VitePress	Vue/JS projects, lightweight	TypeScript	.vitepress/config.ts
   Docusaurus	Large projects, blog + docs	TypeScript	docusaurus.config.js

3. Initialize chosen SSG:

   MkDocs Material:

   uvx mkdocs new .  # or uv add --dev mkdocs-material

   Generate mkdocs.yml:

   site_name: <Project Name>
   site_url: https://<owner>.github.io/<repo>/
   theme:
     name: material
     features:
       - content.code.copy
       - navigation.sections
       - navigation.expand
       - search.suggest
   nav:
     - Home: index.md
     - Getting Started: getting-started.md
     - API Reference: api/index.md
     - Contributing: contributing.md
   markdown_extensions:
     - admonition
     - pymdownx.highlight
     - pymdownx.superfences
     - pymdownx.tabbed:
         alternate_style: true

   VitePress:

   bun add -d vitepress

   Generate .vitepress/config.ts

   Docusaurus:

   bunx create-docusaurus docs classic --typescript

4. Generate initial doc pages:

   • docs/index.md — Project overview (from README or manifest)
   • docs/getting-started.md — Installation + quick start
   • docs/api/index.md — API reference (from code analysis)
   • docs/contributing.md — Development setup + guidelines

5. Add scripts to package.json / Makefile:

   • docs:dev — mkdocs serve / vitepress dev / docusaurus start
   • docs:build — mkdocs build / vitepress build / docusaurus build

6. Output summary of created files + how to preview locally

Edge cases:

• Docs already exist with different SSG → don't suggest migration, work with existing
• No package.json (non-JS project) → MkDocs is the natural choice
• Existing markdown files in docs/ but no SSG → offer to add SSG config around existing content

/docs:api

Purpose: Generate API reference documentation from source code.

Behavior:

1. Detect project type and API surface:

   Type	What to document	Source
   REST API	Endpoints, methods, request/response	Route files, OpenAPI spec
   Library	Exported functions, classes, types	Source files, JSDoc/docstrings
   CLI	Commands, flags, options	Command definitions
   GraphQL	Queries, mutations, types	Schema files

2. For each API element, generate documentation:

   ## `createUser(options)`
   
   Create a new user account.
   
   ### Parameters
   
   | Name | Type | Required | Description |
   |------|------|----------|-------------|
   | `options.email` | `string` | Yes | User email address |
   | `options.name` | `string` | No | Display name |
   
   ### Returns
   
   `Promise<User>` — The created user object.
   
   ### Example
   
   \`\`\`typescript
   const user = await createUser({
     email: "alice@example.com",
     name: "Alice",
   });
   \`\`\`

3. Organize API docs:

   • Group by module/file/resource
   • Create navigation structure
   • Add type definitions section if TypeScript

4. If OpenAPI/Swagger spec exists → generate from spec

5. Output: created/updated doc files

Edge cases:

• No public API (internal project) → skip or ask user what to document
• Mixed API types (REST + library) → separate sections
• Undocumented code → generate from function signatures + parameter types

/docs:deploy (new)

Purpose: Set up GitHub Pages deployment via GitHub Actions.

Behavior:

1. Detect SSG from config files

2. Generate .github/workflows/docs.yml:

   MkDocs Material:

   name: Deploy Docs
   on:
     push:
       branches: [main]
       paths: ['docs/**', 'mkdocs.yml']
     workflow_dispatch:
   
   permissions:
     contents: read
     pages: write
     id-token: write
   
   jobs:
     deploy:
       runs-on: ubuntu-latest
       environment:
         name: github-pages
         url: ${{ steps.deployment.outputs.page_url }}
       steps:
         - uses: actions/checkout@v4
         - uses: actions/setup-python@v5
           with:
             python-version: '3.12'
         - run: pip install mkdocs-material
         - run: mkdocs build --strict
         - uses: actions/upload-pages-artifact@v3
           with:
             path: site/
         - id: deployment
           uses: actions/deploy-pages@v4

   VitePress:

   # Similar structure with bun install + vitepress build

3. Check GitHub Pages settings:

   gh api repos/{owner}/{repo}/pages 2>/dev/null || echo "Pages not enabled"

4. If Pages not enabled → provide instructions:

   • Go to Settings → Pages → Source: GitHub Actions

5. Output: workflow file created + next steps

Edge cases:

• Workflow already exists → offer to update or create alongside
• Custom domain → add CNAME file to docs output
• Monorepo → deploy from subdirectory

Hooks

PostToolUse: docs_outdated

Trigger: Edit or Write tool, when modifying files that have corresponding documentation:

• API route changes → suggest updating API docs
• README changes → suggest syncing with docs site
• Config changes → suggest updating configuration docs

Behavior:

• Output: 💡 Code change may affect docs. Run /docs:generate to check for outdated documentation.
• Informational only, do not block

File Manifest

File	Est. Lines	Purpose
commands/generate.md	110-130	Generate/update documentation
commands/api.md	90-110	Generate API reference
commands/deploy.md	80-100	Set up GitHub Pages deployment
hooks/docs_outdated.md	25-35	Suggest docs updates on code changes
README.md	150-180	Full plugin documentation
.claude-plugin/plugin.json	15-20	Plugin manifest

README Outline

1. Overview — Markdown docs in version control, published to GitHub Pages
2. Quick Start — Installation + /docs:generate + local preview
3. Commands — Table with all 3 commands
4. SSG Comparison — When to use MkDocs vs VitePress vs Docusaurus
5. GitHub Actions Workflow — Reference workflow for each SSG
6. API Documentation — How API docs are generated per project type
7. Keeping Docs Current — How the outdated hook helps
8. Customization — Theming, navigation, plugins per SSG

Prerequisites

• One of: uv/pip (for MkDocs), bun/npm (for VitePress/Docusaurus)
• gh CLI (for Pages setup verification)
• GitHub repository with Pages enabled

Quality Checklist

• Each command .md is 60+ lines with concrete steps
• README is 100+ lines with examples and reference tables
• SSG comparison table helps users choose
• GitHub Actions workflow templates are complete and tested
• Plugin provides clear value (SSG setup + workflow generation + API docs)