CLI documentation generator for WordPress plugins and themes. Parses PHP, JS, and CSS source code and produces static developer documentation sites and MCP server references.
- PHP parsing — functions, classes, constants, hooks (actions & filters), REST API endpoints (
register_rest_route), REST API fields (register_rest_field) - JS parsing — Gutenberg block registration (
block.json), WordPress JS APIs - CSS parsing — design tokens and custom properties
- Static site output — Next.js 16 site with Tailwind CSS 4, sidebar nav, and FlexSearch-powered search
- Skin system — 8 built-in skins (
default,dark-pro,midnight,sandstone,sunset,syntax,terminal,wordpress) plus custom skin JSON and token overrides - MDX guides — author onboarding/tutorial content alongside auto-generated reference docs
- MCP server — exposes parsed references as a Model Context Protocol HTTP server
- Validate command — lint your plugin/theme source before generating docs
- Collection mode — document multiple plugins/themes as a monorepo
- JSON output —
--jsonflag for CI/tooling integration
- Node.js 20+
- Any of npm 10+, pnpm 9+, or yarn (end users install the published package with whichever they prefer; the repo itself is developed with pnpm)
npm install -g @iwritec0de/wpdocsOr run without installing:
npx @iwritec0de/wpdocs <command>Interactively scaffold a docs.config.json in your plugin or theme directory.
wpdocs init ./my-pluginParse source and generate a static documentation site.
wpdocs generate ./my-plugin
wpdocs generate ./my-plugin --output-dir ./docs-site
wpdocs generate ./my-plugin --skin dark-pro
wpdocs generate ./my-plugin --guides ./docs/guidesValidate your plugin or theme source for common documentation issues before generating.
wpdocs validate ./my-plugin
wpdocs validate ./my-plugin --exclude 'tests/**' --exclude 'vendor/**'
wpdocs validate ./my-plugin --jsonGenerate docs and serve a local preview.
wpdocs preview ./my-plugin
wpdocs preview ./my-plugin --port 3001Start the MCP server to expose parsed references to AI tools.
wpdocs mcp ./my-plugin
wpdocs mcp ./my-plugin --port 8080| Flag | Alias | Description |
|---|---|---|
--config | -c | Path to docs.config.json |
--output-dir | -o / --output | Override output directory (default: ./docs-output) |
--guides | Path to a folder of MDX guide content | |
--skin | Built-in skin name or path to skin JSON | |
--tokens | Path to token overrides JSON (layered on skin) | |
--type | plugin | theme | collection | |
--exclude | Glob patterns to exclude (repeatable) | |
--port | -p | Port for MCP/preview server (default: 3000) |
--verbose | -v | Detailed output during generation |
--dry-run | Parse and report without writing output | |
--json | Machine-readable JSON output (for CI/tooling) |
Create a docs.config.json at your plugin/theme root (or run wpdocs init to scaffold one):
{
"name": "My Plugin",
"type": "plugin",
"source": "./src",
"skin": "default",
"guides": "./docs/guides",
"site": {
"title": "My Plugin Docs",
"description": "Developer documentation for My Plugin",
"logo": "./assets/logo.svg",
"githubUrl": "https://github.com/example/my-plugin",
"navLinks": [
{ "label": "Support", "href": "https://example.com/support" }
]
}
}| Field | Type | Description |
|---|---|---|
name | string | Project name |
version | string? | Project version |
type | "plugin" | "theme" | "collection" | Project type (default: "plugin") |
source | string | Path to source root (relative to config, default: "./") |
exclude | string[] | Glob patterns to exclude (default: ["vendor/**", "node_modules/**"]) |
output | string | Output directory (default: "./docs-output") |
guides | string? | Path to MDX guide content folder |
skin | string? | Built-in skin name or path to custom skin JSON |
tokens | string? | Path to token overrides JSON (layered on skin) |
site.title | string? | Documentation site title |
site.description | string? | Documentation site description |
site.baseUrl | string | Base URL path (default: "/") |
site.logo | string? | Path to logo image |
site.githubUrl | string? | GitHub repo URL (shown in top nav) |
site.navLinks | {label, href}[]? | External links in top navigation |
mcp.enabled | boolean | Enable MCP reference output (default: false) |
mcp.output | string | MCP output directory (default: "./mcp-reference") |
Built-in skins: default, dark-pro, midnight, sandstone, sunset, syntax, terminal, wordpress.
Use a built-in skin by name:
{ "skin": "midnight" }Or point to a custom skin JSON file:
{ "skin": "./my-skin.json" }Layer token overrides on top of any skin:
{
"skin": "default",
"tokens": "./brand-tokens.json"
}Place MDX files in a guides directory organized by section:
docs/guides/
intro/
_meta.json # { "title": "Getting Started", "order": 1 }
welcome.mdx
installation.mdx
advanced/
_meta.json
hooks.mdx
Reference the guides folder in your config:
{ "guides": "./docs/guides" }Document multiple plugins as a unified portal. Put a docs.config.json at the collection root:
{
"name": "My Plugin Suite",
"type": "collection",
"source": "./",
"groups": [
{ "name": "Core", "plugins": ["my-core-plugin"] },
{ "name": "Extensions", "plugins": ["my-addon-a", "my-addon-b"] }
]
}Each immediate subdirectory is parsed as a separate plugin. The output includes per-plugin sites, a collection index, and a combined MCP reference.
wpdocs generate ./my-plugin-suiteThe output is a static Next.js site with:
- Overview — plugin summary with stat cards (function/class/hook/endpoint counts)
- PHP Reference — functions, classes, and constants with params, return types, source links
- Hooks — actions and filters with dispatch arg counts and parameter tables
- JavaScript API — JS functions with the same detail as PHP reference
- REST API — endpoints with method badges, route paths, parameters, and custom fields
- CSS Tokens — design token listing with values and scopes
- Guides — MDX-authored content with callouts, code blocks, and tabs
- Changelog — parsed from
CHANGELOG.md - Search — FlexSearch-powered modal (
Cmd+K) indexing all reference items and guides
Three example setups are included to exercise all three type modes:
wpdocs generate examples/example-pluginA comprehensive WordPress plugin with hooks, REST API endpoints, REST fields, JS/CSS, block.json, guides, and a CHANGELOG.
wpdocs generate examples/example-themeA WordPress block theme with style.css header, theme.json, template parts, custom hooks, CSS design tokens, and guides.
wpdocs generate examples/example-plugin-suiteA base plugin with two extension plugins demonstrating cross-plugin hook relationships, grouped REST endpoints, and collection mode output.
git clone https://github.com/iwritec0de/wordpress-dev-docs.git
cd wordpress-dev-docs
pnpm install
pnpm run dev -- generate ./examples/example-plugin # One-shot run (exits when done)
pnpm run dev:watch -- preview ./examples/example-plugin # Watch mode — CLI reruns on src changes
pnpm test# Run tests
pnpm run test:coverage # Coverage report
pnpm run typecheck # Type check
pnpm run lint # Lint
pnpm run build # Production buildThe repo uses pnpm as its package manager (pinned via packageManager in package.json). Enable it via Corepack (corepack enable) or install directly (npm install -g pnpm).
src/
cli/ # Ink CLI app + commands (generate, init, validate, preview, mcp)
parser/ # PHP, JS, CSS parsers + WordPress-specific extractors
generator/ # Site scaffold + MCP reference builder
config/ # Config schema (Zod) + loader
validator/ # Source validation rules
mcp-server/ # MCP server runtime (HTTP)
packages/
site-template/ # Next.js site template + built-in skins
examples/
example-plugin/ # Single WordPress plugin
example-theme/ # WordPress block theme
example-plugin-suite/ # Plugin collection (base + 2 extensions)
MIT