Vaulthalla Logo

Payload Markdown Docs

GitHub Workflow Status npm npm downloads license

@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.

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 helpers, 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, sidebars, and nav links from Next.

Dynamic sitemap

Add docs records, docs set URLs, AI discovery files, and skill artifacts to src/app/sitemap.ts.

Agent skill

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

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 global Trusted owner/repository checks
  • CLI commands for validate, manifest, plan, keygen, and signed push
  • 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, and navbar helpers
  • static asset storage for skills, llms.txt, and llms-full.txt
  • public asset route installer for Next App Router apps
  • sitemap support for static AI routes and native skill artifacts
  • Docs Set Admin Manager with generated doc review and draft publish action
  • local Codex and Claude skill installer
  • canonical agent skill artifacts under /skills

What Is Not Implemented

  • 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.

  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 payload-markdown-docs 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.