V1 Migration Notes

Upgrading an existing 1.0.x install? See Upgrading to 1.1.

The v1 package surface uses docs sets, slug-derived routes, server-owned sync authority, native agent skill assets, and a narrow public package API.

Admin Records

For each docs package:

1. Create a docs set in Docs Globals > Sets.
2. Use the package source id as the slug.
3. Set the branch, usually main.
4. Add a group only when the route needs nesting.
5. Add GitHub OIDC owner trust in Docs Globals > Access.
6. Add Ed25519 public keys in Docs Globals > Access if local signed pushes are still needed.

Routes are derived from group slugs and the docs set slug. GitHub OIDC audience is derived from the docs set slug.

Removed Setup Knobs

Remove these from docs set records, plugin config, scripts, and docs:

• manual route values
• source root values
• plugin-level source allowlists
• per-set Ed25519 keys
• per-set GitHub repository owner lists
• OIDC audience flags
• OIDC issuer/JWKS/skew options
• workflow restrictions unless advanced security is explicitly enabled
• presentation and SEO placeholder fields

CLI Changes

The npm package no longer provides the supported CLI surface. Replace the old npm binary invocation:

1pnpm exec payload-markdown-docs push ...

with the native binary:

1pmdocs push ...

Use:

1pmdocs push \2  --endpoint "$DOCS_SYNC_ENDPOINT" \3  --source <docs-set-slug> \4  --github-oidc

Do not pass route or OIDC audience flags. In GitHub Actions workflow templates, pass --source explicitly with the docs set slug.

Skill-First AI Workflow

AI-facing support comes from native skill packs.

Do not create or maintain:

• index.ai.yml
• index.ai.yaml
• docs set aiExport JSON
• AI export manifest parsing
• raw Markdown export route helpers
• payload-markdown-docs.md
• /plugins/payload-markdown-docs.md

Use repo-local Markdown files under /docs for human documentation source. Use the canonical skill artifacts under /skills/payload-markdown-docs/<agent>/ for agent workflow instructions. The CLI installer copies those artifacts into project-local agent paths for Codex and Claude.

Sitemap AI Artifacts

Generated sitemap output now includes canonical human docs routes by default. Raw AI-facing artifacts are no longer listed in sitemap.xml unless explicitly requested:

• llms.txt and llms-full.txt require includeLlms: true.
• native skill routes such as /skills/codex, /skills/codex/SKILL.md, and /skills/codex.zip require includeSkills: true.
• stored generic static assets require includeAssets: true.

includeAssets does not imply llms or skill routes. Served asset endpoints are unchanged; this only controls crawler discovery from the sitemap helper.

Repairing Stale Docs Routes

Before docs set and docs group changes rewrote generated docs routes (see Changing Docs Set Routes), changing a docs set's group, slug or routeMode, or a group's slug or parent, left generated docs on their old routes until the next sync. To fix such data without a sync, run repairDocsRoutes once, for example from a Payload migration or a payload run script:

1import { repairDocsRoutes } from 'payload-markdown-docs/migrations'2 3export async function up({ payload, req }: MigrateUpArgs): Promise<void> {4  const result = await repairDocsRoutes({ payload, req })5 6  payload.logger.info({ msg: 'Repaired docs routes', sets: result.sets })7}

It compares every generated doc's route with its sourcePath and the current docs set route, so it needs no record of the old routes, and rewrites the published row, the latest draft and the docs set's assets. Options:

• docsSetId: repair one docs set
• dryRun: true: report without writing
• collections: custom collection slugs (docs, docsAssets, docsGroups, docsSets)

Docs whose new route another doc already holds stay where they are and are listed under collisions; records that cannot be placed are listed under unresolved. It is safe to run more than once. Saving a published docs set in the admin repairs that set the same way, and a sync rewrites every route it manages.