Quick Start

This quick start assumes the conventional docs package layout and a docs set slug of main-docs.

Create Admin Records

In Docs Globals > Sets, create:

• title: Main Docs
• slug: main-docs
• branch: main
• optional group: a group such as plugins when you want nested routes

In Docs Globals > Access, create a GitHub OIDC record:

• type: GitHub OIDC
• owner: your GitHub owner or organization
• limitRepos: off for the normal owner-level trust model

The set slug is the manifest source. The route base is derived from the optional group and the set slug.

Source Layout

1docs/2  index.md3skills/4  main-docs/5    codex/6      SKILL.md7    claude/8      SKILL.md

Markdown docs become manifest files. Skills become manifest assets, so skill files do not need docs frontmatter. AI discovery files are generated from synced docs, docs set metadata, dependencies, and skills.

Install An Agent Skill

In the docs set target application, install local agent skills so Codex or Claude has project-specific guidance for package structure, supported frontmatter, validation, sync safety rules, and Payload Markdown authoring.

1pnpm exec payload-markdown-docs install skill --agent codex2pnpm exec payload-markdown-docs install skill --agent claude

The Codex installer writes .agents/skills/payload-markdown-docs/, .agents/skills/payload-markdown/, and creates or updates AGENTS.md. The Claude installer writes .claude/skills/payload-markdown-docs/ plus .claude/skills/payload-markdown/ and does not modify AGENTS.md by default. Neither install syncs docs, calls Payload, or publishes content.

Install Public Asset Routes

If the consuming Next app should serve generated /llms.txt, /llms-full.txt, docs-set llms files, or skill URLs outside /api, commit the generated route files:

1pnpm exec payload-markdown-docs install routes --payload-app "src/app/(payload)"

Those route files delegate to the plugin-owned asset handlers. Without them, a frontend catch-all can return HTML 404 pages even when /api/... asset URLs work.

Validate Local Docs

1pnpm exec payload-markdown-docs validate --source main-docs

Generate A Manifest

1pnpm exec payload-markdown-docs manifest --source main-docs --pretty

Preview A Plan

1pnpm exec payload-markdown-docs plan --source main-docs

Push From GitHub Actions

1pnpm exec payload-markdown-docs push \2  --endpoint "$DOCS_SYNC_ENDPOINT" \3  --source main-docs \4  --github-oidc

When the docs set slug matches the repository name, --source can be omitted in GitHub Actions and the CLI infers it from GITHUB_REPOSITORY.

To publish during sync, add --publish and make sure the server allows publishing. See publishing.