Guide

Plugin documentation

Narrative docs for PRC plugins live under docs/plugins/<plugin-slug>/. DocsPress syncs the whole docs/ tree to the wiki, so this layout is also the WordPress Page tree.

Prefer this tree over legacy plugins/<plugin>/docs/ paths. Update old links when you touch them.

Use the prc-plugin-docs skill (.cursor/skills/prc-plugin-docs/) when creating, migrating, or maintaining these docs.

Standard layout

docs/plugins/<plugin-slug>/
  index.md                 # required landing page (all audiences)
  user-guide.md            # optional — editors / publishers
  architecture.md          # optional — maintainers
  rest-api.md              # optional — stable custom REST contracts
  abilities.md             # optional — WordPress Abilities API contracts
  troubleshooting.md       # optional — recurring support failures
  migration-guide.md       # optional — upgrade steps that need a human
  blocks/                  # optional — block narratives (new multi-block plugins)
    <block-slug>.md
  images/                  # optional — screenshots and diagrams
  release-notes/           # optional — curated wiki release history
    <version>.md

Use lowercase kebab-case for new filenames. Do not rename published paths only for cosmetics.

Required

When a plugin has a docs folder, it must have index.md.

index.md is the plugin landing page for every audience. It is not the full developer guide.

Include:

  • Short description of what the plugin does
  • Who should use it (editors, developers, both)
  • Links to the optional docs that exist
  • Package name (for example @prc/chart-builder) and source path under plugins/

Optional files (earn them)

FileAudienceCreate when
user-guide.mdEditors / publishersThere is a real editorial workflow
architecture.mdMaintainersConcepts, data flow, or tier boundaries need explanation
rest-api.mdConsumersStable custom routes that other code or tools call
abilities.mdConsumers / AIThe plugin registers WordPress Abilities
troubleshooting.mdEditors + maintainersThe same failures keep showing up in support
migration-guide.mdMaintainers / editorsAn upgrade needs manual steps
blocks/<block-slug>.mdMixedSeveral blocks need narratives beyond block.json
images/AllLocal media for the guides above
release-notes/AllThe wiki needs curated version history

Do not create empty stubs. Skip a file until there is real content.

Do not

  • Keep both README.md and index.md in the same folder (DocsPress maps both to the folder landing Page)
  • Require a Markdown page for every shipped block (block.json owns attributes and supports)
  • Create rest-api.md only because a CPT sets show_in_rest or the editor uses an internal endpoint
  • Put private runbooks, credentials, or incident notes under docs/ (this tree syncs to WordPress)
  • Invent commands, routes, caps, or UI that the source does not implement

Block Library exception

prc-block-library narratives live at docs/plugins/prc-block-library/blocks/<block-slug>.md. Maintain those pages with the prc-plugin-docs skill. The optional helper bin/docs/gen-block-lib-list.js can still rebuild the autogenerated index links (./blocks/<block-slug>.md) if you run it with node directly.

Keep the generator, block-doc sync rule, and stop hook aligned with this path.

DocsPress notes

  • Directory names become Page parents under the wiki docs root
  • index.md (or README.md) represents the containing directory
  • Renames can look like trash + recreate under DocsPress delete-mode: trash
  • Prefer relative links inside docs/ so DocsPress can rewrite them
  • Page shape for new and touched pages: frontmatter title, body sections at ##. The DocsPress theme supplies the Page h1. Convert # titles when you migrate a page. Do not rewrite untouched legacy pages only for cosmetics
  • Markdown and Gutenberg blocks: follow .agents/skills/generate-docs-from-source/SKILL.md sections 3 and 4. Do not duplicate that catalog here. Local block registrations in plugins/docspress-blocks/ win if they disagree with skill examples
  • Keep Version Switcher, Version Notice, and was-this-helpful out of plugin Page Markdown (Site Editor owns those)
  • Production Pages update after a production deploy Slack notification (mode: reconcile on the release tag). A daily propose run, and the same workflow's Run workflow button, open a rolling docspress/wordpress-sync PR for WordPress-only edits. See RELEASING.md.

Local sync helpers (token in ./.secrets, never commit it):

npm run docs:sync:local:dry-run
npm run docs:sync:local

Plugins

Was this helpful?