DocsPress is an AI-first documentation system for teams that want people and coding agents reading the same source. Markdown stays beside the code it explains; WordPress turns it into a branded, editable documentation experience made of native Pages and Gutenberg blocks.
AI-first from discovery to maintenance
DocsPress gives text-first clients a native path through the documentation. The root /llms.txt file indexes every published, source-backed Page. Replace a Page route’s trailing slash with .md to fetch its exact reviewed Markdown with the text/markdown content type—no HTML shell to parse and no reconstructed source.
-
Discover with llms.txt
An agent reads one small index of absolute links instead of crawling navigation HTML or guessing routes.
-
Read exact Markdown
Every source-backed Page has a
.mdrepresentation with its frontmatter, examples, tables, and supported block comments intact. -
Improve the source
Repository-aware DocsPress skills help coding agents generate or update documentation from verified code evidence, ready for review.
Readers get the complete WordPress experience. Agents and retrieval systems get discoverable, stable Markdown from the same reviewed source.
Read Make documentation AI-friendly for the endpoint contract, permissions, and verification commands.
Make the complete site yours
DocsPress includes a native block theme rather than a fixed documentation frontend. Use the WordPress Site Editor to change the header, documentation navigation, article tools, table of contents, footer, homepage, posts, archives, search results, comments, and alternate Page layouts.
Global Styles can switch the whole system—not only its colors. The default DocsPress design and the WordPress.org, WordPress.com, and Jetpack families each define coordinated typography, color, spacing, corner, heading, and component treatments. Nine additional palettes provide light and dark brand directions, while native per-block controls let one surface differ without breaking the site-wide system.
Follow Customize the theme in the Site Editor for the complete editing map, or read Why DocsPress? to compare this WordPress-native model with a separately built documentation site.
Use blocks made for technical documentation
Markdown stays portable, but technical explanations do not have to look like plain prose. DocsPress adds editable Gutenberg blocks for connected flows, file trees, prompts, terminal sessions, code tabs, API requests, callouts, results, audience paths, and more.
Use Markdown syntax when it communicates clearly, then add a structured block when sequence, hierarchy, commands, or outcomes deserve a stronger visual treatment. The converter preserves the supported block comments in source, so the GitHub and WordPress representations stay aligned.
Read Gutenberg blocks for the full schema or open the block kitchen sink to see every component together.
Choose a starting point
Start here
Where are your docs today?
Choose the workflow that matches the current state of your repository.
Both paths use repository-aware skills and end with the same reviewed Markdown-to-WordPress workflow. The difference is whether a usable documentation tree already exists.
Install DocsPress with your coding agent
Install both skills into the repository that owns the documentation:
npx skills add Automattic/docspress --all --full-depth
npx skills listThen follow Publish existing docs or Create docs with AI. Each path provides a focused, copy-ready agent prompt.
How DocsPress works
-
.claude/-
skills/-
docspress-install/ -
generate-docs-from-source/
-
-
-
.github/-
workflows/-
sync-docs.yml
-
-
-
docs/-
index.md -
publish-existing-docs/-
index.md -
first-sync.md
-
-
create-docs-with-ai/-
index.md -
review-and-publish.md
-
-
- Authors and agents can update Markdown under
docs/, while editors can update existing managed Pages in Gutenberg. - The GitHub Action converts Markdown into Gutenberg blocks and Gutenberg changes back into focused Markdown edits.
- DocsPress compares both versions with their shared management marker.
- GitHub-only changes update WordPress; WordPress-only changes open a pull request; two-sided changes stop as conflicts.
Read Publish existing docs for the safe synchronization sequence, Create docs with AI when documentation must be generated first, or Authoring documentation for the Markdown contract.
See Why DocsPress? for a practical comparison with Docusaurus and the cases where keeping WordPress as the publishing surface removes an entire parallel docs stack.
Keep documentation synchronized
Prove the connection with workflow_dispatch, status: draft, and dry-run: true. After the dry run and draft Page tree are approved, add this path-scoped trigger:
on: push: branches: [main] paths: - "docs/**/*.md" - "docs/**/*.markdown" - "docs/**/*.json" - ".github/workflows/sync-docs.yml" workflow_dispatch:Every merged documentation change can flow from GitHub to the same WordPress Page hierarchy without maintaining a second copy.
Read GitHub to WordPress and WordPress to GitHub separately, or follow the complete continuous synchronization guide before enabling automatic writes.
Explore the documentation
- Publish existing docs: connect a Markdown tree, authenticate, and run the first safe sync.
- Create docs with AI: generate a source-grounded documentation tree, review it, and hand it to the publishing workflow.
- Why DocsPress?: compare the WordPress-native model with a Docusaurus static site.
- Authoring: structure pages and use Markdown or DocsPress Gutenberg blocks.
- Guides: customize the complete theme in the Site Editor, synchronize in either direction, prevent merge loops, and control routes with manifests or redirects.
- Reference: Action inputs, CLI behavior, REST reconciliation, theme, and block schemas.
- Troubleshooting: diagnose authentication, conflicts, links, and workflow failures.