@valkyrianlabs/payload-markdown-docs 0.5.3 → 0.6.0

package/README.md

@@ -73,6 +73,10 @@ to a matching docs set from the configured branch.
 
 ## Render In Next
 
+The plugin does not mutate your Pages collection and does not register public
+frontend routes. Add route handlers in your Next app where you want docs to
+render.
+
 ```tsx
 import config from '@payload-config'
 import {
@@ -108,6 +112,37 @@ const docsLinks = await getPayloadMarkdownDocsLinks({ payload })
 // [{ label: 'Payload Markdown Docs', url: '/plugins/payload-markdown-docs' }]
 ```
 
+## Serve Raw Markdown
+
+The AI-facing raw Markdown export is a route-handler response, not a generated
+Payload Page. Add a `route.ts` at the exported path, usually the value from
+`docs/index.ai.yml`:
+
+```ts
+// app/(frontend)/plugins/payload-markdown-docs.md/route.ts
+import config from '@payload-config'
+import { createPayloadMarkdownDocsMarkdownResponse } from '@valkyrianlabs/payload-markdown-docs/next'
+import { notFound } from 'next/navigation'
+import { getPayload } from 'payload'
+
+export async function GET() {
+  const payload = await getPayload({ config })
+  const response = await createPayloadMarkdownDocsMarkdownResponse({
+    payload,
+    path: '/plugins/payload-markdown-docs.md',
+  })
+
+  if (response) {
+    return response
+  }
+
+  notFound()
+}
+```
+
+The response is `text/markdown; charset=utf-8` and is assembled from synced
+docs records using `docs/index.ai.yml` when present.
+
 ## Validate Locally
 
 In an app or docs repository that has installed this package:
@@ -127,6 +162,19 @@ pnpm cli validate ./docs --source payload-markdown-docs
 In GitHub Actions, `--source` can be omitted when the docs set slug matches the
 repository name. The CLI infers it from `GITHUB_REPOSITORY`.
 
+## Maintain Docs With Codex
+
+In a docs set target application, install the local Codex skill so agents have
+repo-local guidance for maintaining Markdown docs, frontmatter, `index.ai.yml`,
+validation, and sync safety rules.
+
+```bash
+pnpm exec payload-markdown-docs install skill --codex
+```
+
+The installer writes `.agents/skills/payload-markdown-docs/`. It does not sync
+docs, call Payload, or publish content.
+
 ## Publish From GitHub Actions
 
 ```yaml

package/dist/skills/codex/SKILL.md

@@ -1,3 +1,7 @@
+---
+name: payload-markdown-docs
+description: Use this skill when maintaining Git-backed documentation for a project that uses `@valkyrianlabs/payload-markdown-docs`.
+
 # Payload Markdown Docs Skill
 
 Use this skill when maintaining Git-backed documentation for a project that uses `@valkyrianlabs/payload-markdown-docs`.
@@ -11,8 +15,10 @@ The docs source lives in `{{docsRoot}}` unless the user says otherwise. Edit Mar
 - Use supported frontmatter only.
 - Keep internal docs links root-relative inside the docs set, such as `/getting-started/quick-start`.
 - Use `payload-markdown` directives only when they are supported.
+- Keep formatting plain Markdown: supported frontmatter, one H1, clear H2/H3 sections, root-relative links, and supported directives.
 - Do not invent directives, frontmatter fields, CLI flags, sync modes, or runtime features.
 - Do not describe unsupported features as implemented.
+- Do not add MDX, arbitrary YAML objects, inline frontmatter arrays, HTML widgets, or one Payload Page per Markdown file.
 - Run validation before finishing docs edits.
 - Treat sync and publishing as CMS/server-owned. The request may ask; Payload
   docs sets and plugin config decide.
@@ -39,6 +45,7 @@ Rules for `index.ai.yml`:
 - Do not show the manifest in human docs navigation.
 - Do not render the manifest as a normal docs page.
 - Use it as the canonical ordering source for the `.md` export.
+- Remember that the `.md` export is served by a Next route handler, not by a generated Payload Page.
 - Avoid backend hand-sorting unless the project already has a docs sort field.
 
 Ordering source preference:
@@ -154,6 +161,7 @@ Sync writes require `sync.allowWrites: true`. Publishing additionally requires `
 ## References
 
 - `reference/payload-markdown-directives.md`
+- `reference/formatting.md`
 - `reference/frontmatter.md`
 - `reference/workflow.md`
 - `reference/sync.md`

package/dist/skills/codex/reference/formatting.md

@@ -0,0 +1,24 @@
+# Formatting
+
+Keep docs as plain Markdown that validates before sync.
+
+Expected shape:
+
+- supported frontmatter at the top
+- one H1 for the page title
+- H2 and H3 sections for structure
+- root-relative internal links, such as `/workflow/publishing`
+- supported `payload-markdown` directives only
+- `index.ai.yml` updated when pages are added, moved, renamed, or removed
+
+Do not add:
+
+- `.mdx` files
+- arbitrary YAML objects
+- inline frontmatter arrays
+- invented directive names or props
+- HTML scripts, iframes, or client-side widgets
+- one Payload Page per Markdown file
+- production docs domains for internal links
+
+Prefer short, concrete sections over long pages with deeply nested headings.

package/dist/skills/codex/reference/frontmatter.md

@@ -35,5 +35,7 @@ Rules:
 - `tags` and `redirectFrom` must use list item syntax.
 - `slug` may contain letters, numbers, and hyphens.
 - Avoid arbitrary nested YAML objects.
+- Avoid inline arrays such as `tags: [getting-started]`.
 - Avoid unsupported fields unless the user accepts validation warnings.
 - Explicit `title` is preferred even though title fallback exists.
+- Use `slug` only to override the final route segment; move files to change route hierarchy.

package/dist/skills/codex/reference/routing.md

@@ -34,3 +34,11 @@ Do not hardcode production docs domains for internal navigation.
 ## Route Adapter
 
 The `/next` export can resolve docs routes and let an app fall back to normal Pages rendering when no docs route matches. It does not mutate Pages.
+
+## Raw Markdown
+
+The AI-facing `.md` export is served by a Next route handler. It is not a
+generated Payload Page and cannot be returned from a `page.tsx` catch-all.
+
+Use `createPayloadMarkdownDocsMarkdownResponse` at the output path from
+`index.ai.yml`, or place AI exports in a dedicated namespace such as `/ai`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valkyrianlabs/payload-markdown-docs",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "Git-backed Markdown documentation sync for Payload CMS, powered by payload-markdown.",
   "bin": {
     "payload-markdown-docs": "./dist/cli/index.js"