Installation

Install the docs workflow package together with its peer packages:

1pnpm add @valkyrianlabs/payload-markdown-docs @valkyrianlabs/payload-markdown @payloadcms/plugin-seo

@valkyrianlabs/payload-markdown (Markdown field and renderer) and @payloadcms/plugin-seo (docs-set SEO fields) are peer dependencies: the plugin registers admin components from both packages in your app's import map, so your app must install them directly. Installing them yourself also keeps a single copy of payload-markdown, so the payloadMarkdown() options you configure (themes, code highlighting, icons) apply to docs pages too. Register payloadMarkdown() in the same Payload config as payloadMarkdownDocs(). payload, next, react and react-dom are peers as well and are already part of every Payload app.

Styling

Docs pages and components use Tailwind utility classes from both packages. With Tailwind v4, add both packages to your app stylesheet's sources:

1@import "tailwindcss";2@plugin "@tailwindcss/typography";3@source "../node_modules/@valkyrianlabs/payload-markdown/dist";4@source "../node_modules/@valkyrianlabs/payload-markdown-docs/dist";

Adjust the relative paths to where your stylesheet lives. The components expect --color-foreground, --color-border and --color-background theme tokens (shadcn-style text-foreground, border-border, bg-background).

payload-markdown-docs uses payload-markdown for Markdown fields and rendering. It does not duplicate the renderer.

The npm package installs the Payload plugin/runtime integration only. Install the native pmdocs CLI separately anywhere you validate, plan, install routes, generate keys, or publish docs. This keeps docs-only repos and CI jobs from needing a Node dependency install just to run operator commands.

Native CLI

Debian/Ubuntu:

1sudo install -d -m 0755 /etc/apt/keyrings2sudo curl -fsSL https://apt.valkyrianlabs.com/pubkey.gpg \3  -o /etc/apt/keyrings/valkyrianlabs.gpg4sudo chmod 0644 /etc/apt/keyrings/valkyrianlabs.gpg5 6echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/valkyrianlabs.gpg] https://apt.valkyrianlabs.com stable main" | \7  sudo tee /etc/apt/sources.list.d/valkyrianlabs.list > /dev/null8 9sudo apt-get update10sudo apt-get install -y pmdocs11 12pmdocs --version13pmdocs --help

Homebrew:

1brew tap valkyrianlabs/tap2brew install pmdocs3 4pmdocs --version5pmdocs --help

Minimal Plugin Registration

1import { payloadMarkdownDocs } from '@valkyrianlabs/payload-markdown-docs'2import { buildConfig } from 'payload'3 4export default buildConfig({5  plugins: [6    payloadMarkdownDocs({7      enabled: true,8    }),9  ],10})

An enabled plugin registers the default docs infrastructure:

• docs-sets
• docs-groups
• docs-access
• docs
• docs-sync-runs
• docs-sync-nonces

Recommended Server Config

1payloadMarkdownDocs({2  auth: {3    githubOidc: true,4  },5 6  target: {7    enableDrafts: true,8  },9 10  sync: {11    allowWrites: true,12    allowPublish: true,13    allowHardDelete: false,14    deleteBehavior: 'archive',15  },16})

Create a docs set in Payload Admin for each docs package. The docs set slug is the sync source. Routes are derived from the optional group and slug. GitHub OIDC trust records and Ed25519 keys live in Docs Globals > Access.

Next, create keys with keygen, then follow the quick start.