Valkyrian Labs logo

Payload Markdown Docs

:::badges ::badge[GitHub Workflow Status]{ type="github" target="workflow" repo="valkyrianlabs/payload-markdown-docs" workflow="deploy.yml" href="https://github.com/valkyrianlabs/payload-markdown-docs/actions" } ::badge[npm]{ type="npm" target="version" package="@valkyrianlabs/payload-markdown-docs" href="https://www.npmjs.com/package/@valkyrianlabs/payload-markdown-docs" } ::badge[npm downloads]{ type="npm" target="downloads" package="@valkyrianlabs/payload-markdown-docs" href="https://www.npmjs.com/package/@valkyrianlabs/payload-markdown-docs" } ::badge[license]{ type="npm" target="license" package="@valkyrianlabs/payload-markdown-docs" href="https://github.com/valkyrianlabs/payload-markdown-docs?tab=MIT-1-ov-file" }

@valkyrianlabs/payload-markdown-docs publishes Git-backed Markdown documentation into Payload CMS. Developers and agents edit files in a repo-local docs/ folder, CI validates and authenticates a manifest, and the Payload plugin decides what can be synced.

Native CLI split

Install the npm package in the Payload app. Install the native pmdocs binary from Homebrew or the Valkyrian Labs Debian repository wherever docs are validated, planned, signed, and published.

CMS-owned authority

The client sends docs content. Payload docs sets decide where it may go and which source credentials are trusted; plugin config decides whether writes, publishing, or hard delete are permitted.

The package is built around @valkyrianlabs/payload-markdown. That package owns Markdown fields, directive rendering, themes, and authoring UX. This package owns docs ingestion, signed sync, audit records, docs sets, route resolution, and CI/local tooling.

Quick start

Configure the plugin, validate the docs package, install public asset routes, and run the first sync.

Architecture

Understand the docs groups, docs sets, generated docs records, signed endpoint, and route adapter.

Frontend helpers

Render docs routes, metadata, sitemaps, sidebar data, and nav links from Next.

Dynamic sitemap

Add canonical docs records and docs set URLs to src/app/sitemap.ts, with opt-in raw asset entries.

Agent skill

Install local agent guidance for writing docs that validate and sync.

Public API

Use the root, /next, /admin, and /blocks package surfaces intentionally.

What Is Implemented

  • dedicated docs, docs groups, docs sets, sync runs, and nonce collections
  • signed Ed25519 sync endpoint with nonce replay protection
  • GitHub Actions OIDC auth mode with Access owner/repository checks
  • native pmdocs commands for validate, manifest, plan, keygen, install routes, install skill, and signed push
  • Homebrew and Debian installation for the native pmdocs operator CLI
  • server-gated sync writes, publishing, draft behavior, archive behavior, and hard delete
  • route reservations and opt-in Pages collision checks
  • read-only /next route adapter, metadata, sitemap, sidebar data, and navbar helpers
  • generated root and docs-set llms.txt / llms-full.txt endpoints
  • raw asset storage for skills and optional custom static assets
  • public asset route installer for Next App Router apps
  • default sitemap support for canonical docs pages, with opt-in raw asset entries
  • Docs Set Admin Manager with generated doc review and draft publish action
  • local Codex and Claude skill installer
  • canonical agent skill artifacts under /skills

V1 Boundaries

  • existing collection targets
  • block targets
  • inline override editing in the Docs Set Admin Manager
  • automatic frontend route or Page creation in your Next app
  1. 1

    Install

    Add @valkyrianlabs/payload-markdown-docs and @valkyrianlabs/payload-markdown, then install the native pmdocs binary.

  2. 2

    Configure Payload

    Register payloadMarkdownDocs() with explicit write gates, then create a docs set in Payload Admin with a title, slug, branch, and optional group.

  3. 3

    Validate locally

    Run pmdocs validate ./docs --source main-docs.

  4. 4

    Push safely

    Use push --dry-run on pull requests and push --publish on main when the server config allows writes and publishing.

Continue with installation or jump to the GitHub Actions workflow.