@valkyrianlabs/payload-markdown 1.4.0 → 1.4.1

package/skills/payload-markdown/claude/reference/payload-markdown-directives.md

@@ -0,0 +1,246 @@
+# Payload Markdown Directives
+
+Payload Markdown directives are Markdown-native structure. Use labels for visible titles and attributes for behavior.
+
+## Syntax Rules
+
+- Prefer `[Label]` for visible names.
+- Use multiline attributes when a directive has more than one or two attributes.
+- Boolean attributes may be bare only where the directive supports them.
+- Close container directives with `:::` unless a specific structural closer is clearer.
+
+Example:
+
+```md
+:::card[Fast Setup]{
+  href="/getting-started/installation"
+  linkScope="title"
+  icon="@fa-duotone/bolt"
+}
+Install, configure, ship.
+:::
+```
+
+## Directive Inventory
+
+- `:::callout`
+- `:::details`
+- `:::toc`
+- `:::steps`
+- `:::cards`
+- `:::card`
+- `::button`
+- `:::buttons`
+- `:::tabs`
+- `:::tab`
+- `:::section`
+- `:::2col`
+- `:::3col`
+- `:::cell`
+
+## Callouts
+
+Use callouts for information that changes how the reader should interpret or execute a task.
+
+Attributes:
+
+- `variant`: `note`, `info`, `tip`, `warning`, `danger`, or `success`
+- `theme`: `soft`, `solid`, `glass`, or a configured theme
+- `icon`: local icon reference
+- `[Label]` or legacy `title`
+
+```md
+:::callout[Production migration]{variant="danger"}
+Back up production data before reconciling schema changes.
+:::
+```
+
+## Details
+
+Use details for optional information, caveats, error shapes, compatibility notes, or advanced paths.
+
+Attributes:
+
+- `[Label]` or legacy `title`
+- `open`: `open="true"` for initially open
+- `theme`: `default`, `muted`, `glass`, or a configured theme
+
+```md
+:::details[Advanced notes]{theme="glass"}
+These notes are useful after the basic setup is working.
+:::
+```
+
+## Table Of Contents
+
+Use a TOC on long pages with several H2 or H3 sections.
+
+Attributes:
+
+- `[Label]` or legacy `title`
+- `depth`: `1` through `6`
+- `theme`: `default`, `compact`, `sidebar`, or a configured theme
+
+```md
+:::toc[On this page]{depth="3" theme="compact"}
+:::
+```
+
+## Steps
+
+Use steps for ordered procedures. Start each step with a heading.
+
+Attributes:
+
+- `variant`: `default` or `cards`
+- `layout`: `stack` or `grid` for card steps
+- `columns`: `1`, `2`, `3`, `4`, or `auto` for card-step grid layout
+- `numbered`: generated visible numbers for card steps
+- `theme`: steps wrapper theme
+- `stepTheme`: card theme for individual step cards
+
+```md
+:::steps{
+  variant="cards"
+  layout="stack"
+  numbered
+  stepTheme="cyan"
+}
+
+### Install
+
+Install the package.
+
+### Configure
+
+Register the plugin.
+
+:::
+```
+
+## Cards
+
+Use cards for page maps, capability groups, related links, and compact summaries.
+
+`:::cards` attributes:
+
+- `columns`: `1`, `2`, `3`, `4`, or `auto`
+- `href`: inherited or section-level link
+- `linkScope`: `section`, `card`, or `title`
+- `newTab`: open links in a new tab
+- `theme`: cards container theme
+- `cardTheme`: default child card theme
+
+`:::card` attributes:
+
+- `[Label]` or legacy `title`
+- `eyebrow`
+- `icon`
+- `href`
+- `linkScope`: `full` or `title`
+- `newTab`
+- `theme`
+
+Use `linkScope="title"` when the card body contains buttons or links.
+
+```md
+:::cards{
+  columns="3"
+  cardTheme="muted"
+}
+
+:::card[Configuration]{
+  href="/configuration"
+  linkScope="title"
+}
+Code, themes, icons, and renderer defaults.
+:::
+
+:::
+```
+
+## Buttons
+
+Use button links for clear actions. Do not use snippet-only names such as `::button_icon` in source.
+
+`::button` attributes:
+
+- `href`: required
+- `variant`: `primary`, `secondary`, `outline`, `ghost`, or `link`
+- `size`: `sm`, `md`, or `lg`
+- `icon`: local icon reference
+- `iconPosition`: `left` or `right`
+- `newTab`
+- `ariaLabel` for icon-only buttons
+
+`:::buttons` attributes:
+
+- `align`: `left`, `center`, or `right`
+- `stack`: `mobile`, `always`, or `never`
+- `gap`: `sm`, `md`, or `lg`
+
+```md
+:::buttons{align="center" stack="mobile" gap="md"}
+::button[Read Docs]{href="/getting-started" variant="primary"}
+::button[GitHub]{href="https://github.com/valkyrianlabs" variant="secondary" newTab=true}
+:::
+```
+
+## Tabs
+
+Use tabs for equivalent alternatives. Avoid tabs when the content is sequential.
+
+`:::tabs` attributes:
+
+- `default`: selected tab value on first render
+- `theme`: tabs container theme
+- `tabTheme`: default panel theme
+
+`:::tab` attributes:
+
+- `[Label]` or legacy `label`
+- `value`
+- `theme`
+- `disabled`
+
+````md
+:::tabs{default="pnpm" theme="glass" tabTheme="muted"}
+
+:::tab[pnpm]{value="pnpm"}
+```bash
+pnpm add package-name
+```
+:::
+
+:::tab[npm]{value="npm"}
+```bash
+npm install package-name
+```
+:::
+
+:::
+````
+
+## Layout
+
+Use layout directives sparingly for dense overview pages.
+
+- `:::section` supports `theme`.
+- `:::2col` and `:::3col` support `theme` and `cellTheme`.
+- `:::cell` supports `theme`.
+- `:::endcol` explicitly closes an active grid.
+- `:::endsection` explicitly closes an active section.
+
+```md
+:::2col{cellTheme="panel"}
+
+### Field Mode
+
+Use for long-form docs, posts, and articles.
+
+### Block Mode
+
+Use when Markdown is one block in a layout builder.
+
+:::
+```

package/skills/payload-markdown/claude/reference/quality.md

@@ -0,0 +1,48 @@
+# Quality Checklist
+
+Use this checklist before returning generated docs.
+
+## Accuracy
+
+- Public names match source exactly.
+- Defaults are stated only when verified.
+- Deprecated features are labeled as supported legacy paths, not removed behavior.
+- Examples use real import paths, config keys, and commands.
+- Warnings and limitations are visible near the relevant instructions.
+
+## Structure
+
+- One H1 per page.
+- H2 sections follow the user's workflow.
+- TOC appears on long pages.
+- Cards summarize choices or related links.
+- Steps are reserved for sequential work.
+- Details contain optional content, not required setup.
+
+## Directive Hygiene
+
+- Only supported directives are used.
+- Visible titles use `[Label]`.
+- Multiline attributes are used for dense directives.
+- `linkScope="title"` is used for cards containing buttons or links.
+- Button directives include `href`.
+- Icon-only buttons include `ariaLabel`.
+- Tabs have stable `value` attributes.
+
+## Markdown Hygiene
+
+- Internal docs links are root-relative.
+- Fenced code blocks use language tags.
+- Markdown-in-Markdown examples use outer fences longer than inner fences.
+- No MDX imports, JSX widgets, or arbitrary HTML layout.
+- No runtime Tailwind classes in authored Markdown unless the target project explicitly allows it.
+
+## Automated Checks
+
+Run:
+
+```bash
+python3 skills/payload-markdown/codex/scripts/check_payload_markdown_doc.py path/to/docs.md
+```
+
+If working inside a downstream docs package, run its docs validation command as well.

package/skills/payload-markdown/claude/scripts/check_payload_markdown_doc.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""Lightweight checks for docs authored with Payload Markdown directives."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+CONTAINER_DIRECTIVES = {
+    "callout",
+    "details",
+    "toc",
+    "steps",
+    "cards",
+    "card",
+    "buttons",
+    "tabs",
+    "tab",
+    "section",
+    "2col",
+    "3col",
+    "cell",
+}
+LEAF_DIRECTIVES = {"button"}
+ALL_DIRECTIVES = CONTAINER_DIRECTIVES | LEAF_DIRECTIVES
+
+LINK_RE = re.compile(r"\[[^\]]+\]\(([^)]+)\)")
+DIRECTIVE_RE = re.compile(r"^\s*::(?P<colons>:?)(?P<name>[A-Za-z0-9_-]+)\b(?P<rest>.*)$")
+ATTR_RE = re.compile(r"([A-Za-z][A-Za-z0-9_-]*)=(?:\"([^\"]*)\"|'([^']*)'|([^\s}]+))")
+
+
+def strip_frontmatter(text: str) -> str:
+    if not text.startswith("---\n"):
+        return text
+    end = text.find("\n---\n", 4)
+    if end < 0:
+        return text
+    return text[end + 5 :]
+
+
+def iter_content_lines(text: str):
+    in_fence = False
+    fence_marker = ""
+    for index, line in enumerate(text.splitlines(), start=1):
+        stripped = line.strip()
+        fence = re.match(r"^(```+|~~~+)", stripped)
+        if fence:
+            marker = fence.group(1)
+            if not in_fence:
+                in_fence = True
+                fence_marker = marker[:3]
+            elif marker.startswith(fence_marker):
+                in_fence = False
+                fence_marker = ""
+            yield index, line, True
+            continue
+        yield index, line, in_fence
+
+
+def parse_attrs(rest: str) -> dict[str, str]:
+    attrs: dict[str, str] = {}
+    for match in ATTR_RE.finditer(rest):
+        attrs[match.group(1)] = next(value for value in match.groups()[1:] if value is not None)
+    return attrs
+
+
+def check_file(path: Path) -> list[str]:
+    text = path.read_text(encoding="utf-8")
+    body = strip_frontmatter(text)
+    warnings: list[str] = []
+    h1_count = 0
+    stack: list[tuple[str, int]] = []
+
+    for line_no, line, in_fence in iter_content_lines(body):
+        if in_fence:
+            continue
+
+        if re.match(r"^# ", line):
+            h1_count += 1
+
+        for target in LINK_RE.findall(line):
+            if target.startswith(("http://", "https://", "mailto:", "#")):
+                continue
+            if target.endswith(".md") or ".md#" in target:
+                warnings.append(f"{path}:{line_no}: internal docs link should not target .md source: {target}")
+            elif not target.startswith("/"):
+                warnings.append(f"{path}:{line_no}: internal docs link should be root-relative: {target}")
+
+        match = DIRECTIVE_RE.match(line)
+        if not match:
+            continue
+
+        name = match.group("name")
+        is_container = bool(match.group("colons"))
+        rest = match.group("rest")
+
+        if name in {"end", "endcol", "endsection"}:
+            if name == "endcol":
+                while stack and stack[-1][0] not in {"2col", "3col"}:
+                    stack.pop()
+                if stack:
+                    stack.pop()
+            elif name in {"end", "endsection"}:
+                while stack and stack[-1][0] != "section":
+                    stack.pop()
+                if stack:
+                    stack.pop()
+            continue
+
+        if name not in ALL_DIRECTIVES:
+            warnings.append(f"{path}:{line_no}: unsupported Payload Markdown directive: {name}")
+            continue
+
+        if name in LEAF_DIRECTIVES and is_container:
+            warnings.append(f"{path}:{line_no}: leaf directive should use two colons: {name}")
+        if name in CONTAINER_DIRECTIVES and not is_container:
+            warnings.append(f"{path}:{line_no}: container directive should use three colons: {name}")
+
+        attrs = parse_attrs(rest)
+        if name == "button" and "href" not in attrs:
+            warnings.append(f"{path}:{line_no}: button directive should include href")
+        if name == "tab" and "value" not in attrs:
+            warnings.append(f"{path}:{line_no}: tab directive should include a stable value")
+        if name == "card" and attrs.get("linkScope") == "full":
+            warnings.append(f"{path}:{line_no}: use card linkScope=\"title\" when the body may contain links")
+
+        if name in CONTAINER_DIRECTIVES:
+            stack.append((name, line_no))
+
+    if h1_count != 1:
+        warnings.append(f"{path}: expected exactly one H1, found {h1_count}")
+
+    return warnings
+
+
+def main(argv: list[str]) -> int:
+    paths = [Path(arg) for arg in argv]
+    if not paths:
+        print("Usage: check_payload_markdown_doc.py <markdown-file> [...]", file=sys.stderr)
+        return 2
+
+    warnings: list[str] = []
+    for path in paths:
+        if path.is_file() and path.suffix == ".md":
+            warnings.extend(check_file(path))
+
+    for warning in warnings:
+        print(warning)
+
+    return 1 if warnings else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/skills/payload-markdown/codex/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: payload-markdown
+description: Write elegant automated documentation with @valkyrianlabs/payload-markdown. Use when Codex needs to author, rewrite, audit, or structure docs using Payload Markdown directives, theme names, cards, callouts, steps, tabs, TOCs, buttons, and layout primitives.
+---
+
+# Payload Markdown
+
+Use this skill to write documentation that renders well with `@valkyrianlabs/payload-markdown`, especially docs generated or maintained by agents for downstream `@valkyrianlabs/payload-markdown-docs` projects.
+
+This skill is about authoring clean Markdown content with Payload Markdown directives. It is not a Payload CMS implementation guide.
+
+This package stores the Codex variant at `skills/payload-markdown/codex`. When installing into an environment that requires the skill directory name to match `name`, install or copy this subtree as `payload-markdown`.
+
+## Workflow
+
+1. Inspect the source of truth before writing docs: code, README, existing docs, examples, tests, public API, and current package metadata.
+2. Choose a page shape: overview, installation, reference, migration, troubleshooting, release notes, or API guide.
+3. Use normal Markdown for prose and use directives only where they improve scanning, sequencing, comparison, or calls to action.
+4. Prefer readable directive labels such as `[Install]` over legacy `title=""`.
+5. Keep examples copyable. Use long fences when documenting Markdown that contains code fences.
+6. Run `scripts/check_payload_markdown_doc.py` on changed docs before finishing.
+
+## Reference Map
+
+- Read `reference/automated-docs-workflow.md` for source-driven docs generation and audit flow.
+- Read `reference/formatting.md` for frontmatter, headings, links, prose, and fenced examples.
+- Read `reference/payload-markdown-directives.md` for supported directive syntax and recipes.
+- Read `reference/quality.md` before final review or docs drift audits.
+
+## Authoring Defaults
+
+- Use exactly one H1 per page.
+- Put `:::toc[On this page]{depth="3" theme="compact"}` after the intro on long pages.
+- Use `:::callout` for important notes, warnings, tips, and migration hazards.
+- Use `:::steps` for setup, tutorials, and workflows.
+- Use `:::cards` and `:::card` for page maps, feature groups, related links, and summary grids.
+- Use `:::tabs` only for truly parallel alternatives such as package managers or framework variants.
+- Use `:::details` for optional caveats, migration notes, or advanced branches.
+- Use `:::section`, `:::2col`, `:::3col`, and `:::cell` sparingly for dense landing-style docs sections.
+- Avoid unsupported directives, MDX components, arbitrary HTML widgets, and runtime Tailwind classes in authored Markdown.
+
+## Examples
+
+- `examples/docs-page.md`: polished docs page with TOC, cards, steps, callouts, tabs, and details.
+- `examples/reference-page.md`: API/reference style page with structured sections and warnings.
+- `examples/release-notes.md`: release note page using cards, details, and migration callouts.
+
+## Validation
+
+Run the helper on changed Markdown files:
+
+```bash
+python3 skills/payload-markdown/codex/scripts/check_payload_markdown_doc.py docs/**/*.md
+```
+
+If the downstream project uses `@valkyrianlabs/payload-markdown-docs`, also run its docs validation command when available.

package/skills/payload-markdown/codex/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Payload Markdown"
+  short_description: "Write rich Payload Markdown docs"
+  default_prompt: "Use $payload-markdown to write elegant automated documentation with Payload Markdown directives."

package/skills/payload-markdown/codex/examples/docs-page.md

@@ -0,0 +1,97 @@
+---
+title: Installation
+navTitle: Install
+description: Install the package, register the plugin, and render Markdown content.
+order: 20
+status: published
+tags:
+  - getting-started
+  - installation
+---
+
+# Installation
+
+Install the package, enable it for your Payload collections, and render Markdown with the server component.
+
+:::toc[On this page]{depth="3" theme="compact"}
+:::
+
+:::callout[Before you start]{variant="info"}
+This guide assumes a Payload 3 project with a working Next.js app.
+:::
+
+:::steps{
+  variant="cards"
+  layout="stack"
+  numbered
+  stepTheme="cyan"
+}
+
+### Install The Package
+
+```bash
+pnpm add @valkyrianlabs/payload-markdown
+```
+
+### Register The Plugin
+
+Add `payloadMarkdown()` to the Payload config and enable the collections that should receive Markdown fields or blocks.
+
+### Render Content
+
+Use `MarkdownRenderer` for standalone fields and `MarkdownBlockComponent` for `vlMdBlock` entries.
+
+:::
+
+## Configuration Map
+
+:::cards{
+  columns="3"
+  cardTheme="muted"
+}
+
+:::card[Fields And Blocks]{href="/getting-started/fields-and-blocks"}
+Automatic install behavior and manual schema control.
+:::
+
+:::card[Rendering]{href="/getting-started/rendering"}
+Server-first Markdown output, scoped config, and fallback behavior.
+:::
+
+:::card[Code Blocks]{href="/configuration/code-blocks"}
+Shiki languages, themes, line numbers, and full-bleed code.
+:::
+
+:::
+
+## Package Manager Alternatives
+
+:::tabs{
+  default="pnpm"
+  theme="glass"
+  tabTheme="muted"
+}
+
+:::tab[pnpm]{value="pnpm"}
+```bash
+pnpm add @valkyrianlabs/payload-markdown
+```
+:::
+
+:::tab[npm]{value="npm"}
+```bash
+npm install @valkyrianlabs/payload-markdown
+```
+:::
+
+:::tab[yarn]{value="yarn"}
+```bash
+yarn add @valkyrianlabs/payload-markdown
+```
+:::
+
+:::
+
+:::details[When to configure icons]
+Configure local SVG icon packs only when authored content uses `icon="@pack/name"` on buttons, cards, or callouts.
+:::

package/skills/payload-markdown/codex/examples/reference-page.md

@@ -0,0 +1,75 @@
+---
+title: Renderer API
+navTitle: Renderer
+description: Render Markdown fields and blocks with server-first components.
+order: 80
+status: published
+tags:
+  - reference
+  - rendering
+---
+
+# Renderer API
+
+Use the server renderer for Markdown fields and the block component for `vlMdBlock` layout entries.
+
+:::toc[On this page]{depth="3" theme="compact"}
+:::
+
+## Exports
+
+:::cards{
+  columns="2"
+  cardTheme="glass"
+}
+
+:::card[MarkdownRenderer]
+Server component for Markdown strings stored in fields or loaded from another source.
+:::
+
+:::card[MarkdownBlockComponent]
+Server component for Payload block data with `blockType: "vlMdBlock"`.
+:::
+
+:::
+
+## Field Rendering
+
+```tsx
+import { MarkdownRenderer } from '@valkyrianlabs/payload-markdown/server'
+
+export function PostBody({ content }: { content?: null | string }) {
+  return (
+    <MarkdownRenderer
+      collectionSlug="posts"
+      markdown={content}
+      scope="field"
+      variant="docs"
+    />
+  )
+}
+```
+
+:::callout[Collection scope]{variant="tip"}
+Pass `collectionSlug` when collection-level `code`, `themes`, or `config` should apply.
+:::
+
+## Block Rendering
+
+```tsx
+import { MarkdownBlockComponent } from '@valkyrianlabs/payload-markdown/server'
+
+export function RenderMarkdownBlock({ block }: { block: { blockType: 'vlMdBlock'; content: string } }) {
+  return <MarkdownBlockComponent {...block} collectionSlug="pages" />
+}
+```
+
+:::callout[Direct props]{variant="warning"}
+Pass block fields directly with `{...block}`. Do not wrap the data in a `block` prop.
+:::
+
+## Fallbacks
+
+:::details[Empty and warning fallback behavior]
+`emptyFallback` renders when Markdown is empty or whitespace-only. `errorFallback` renders when compilation produces warnings and you prefer not to show the compiled HTML.
+:::