@valkyrianlabs/payload-markdown 1.3.4 → 1.4.1

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.
+:::

package/skills/payload-markdown/codex/examples/release-notes.md

@@ -0,0 +1,69 @@
+---
+title: Version 1.4.0
+navTitle: v1.4.0
+description: New authoring primitives, icon packs, and directive improvements.
+order: 10
+status: published
+tags:
+  - releases
+  - changelog
+---
+
+# Version 1.4.0
+
+Version 1.4.0 improves directive authoring, local SVG icon usage, and rich docs composition.
+
+:::toc[On this page]{depth="3" theme="compact"}
+:::
+
+## Highlights
+
+:::cards{
+  columns="3"
+  theme="spacious"
+  cardTheme="glass"
+}
+
+:::card[Readable Labels]{eyebrow="Authoring"}
+Use `[Title]` directive labels for visible titles instead of dense attribute lists.
+:::
+
+:::card[Local Icons]{eyebrow="Rendering"}
+Reference local SVG packs with `@pack/name` on buttons, cards, and callouts.
+:::
+
+:::card[Safer Links]{eyebrow="Cards"}
+Use `linkScope="title"` when card bodies contain nested links or buttons.
+:::
+
+:::
+
+## Migration Notes
+
+:::callout[No stored content migration required]{variant="success"}
+Existing `title=""` directive attributes remain supported. New docs should prefer `[Label]`.
+:::
+
+:::details[Code config aliases]
+Legacy `config.options` code settings still work, but new docs should use the top-level `code` namespace.
+:::
+
+## Upgrade Steps
+
+:::steps
+
+### Update The Package
+
+```bash
+pnpm up @valkyrianlabs/payload-markdown
+```
+
+### Review Custom Themes
+
+Confirm theme objects use `classes`, not `className`.
+
+### Refresh Examples
+
+Prefer labels, multiline attributes, and card link scopes in new docs.
+
+:::

package/skills/payload-markdown/codex/reference/automated-docs-workflow.md

@@ -0,0 +1,64 @@
+# Automated Docs Workflow
+
+Use this workflow when generating or maintaining docs with Payload Markdown.
+
+## 1. Build The Source Model
+
+Before writing, inspect the real project surface:
+
+- package metadata and exported entry points
+- README and existing docs
+- public types and config names
+- examples, tests, fixtures, and generated types
+- CLI commands, route names, environment variables, and migration notes
+
+Do not describe a feature as implemented unless the source proves it.
+
+## 2. Choose The Page Type
+
+Use the page type to decide which directives belong:
+
+- Overview: cards for page maps, callouts for positioning, short sections.
+- Installation: steps, tabs for package managers, warnings for prerequisites.
+- Usage guide: steps, callouts, details for optional branches.
+- API reference: TOC, dense headings, small cards for related APIs.
+- Migration: danger/warning callouts, steps, details for rollback notes.
+- Troubleshooting: callouts for symptoms, details for error shapes, cards for common causes.
+- Release notes: cards for highlights, details for compatibility notes.
+
+## 3. Draft With A Clear Reading Path
+
+Write the page in this order:
+
+1. H1 with the page topic.
+2. One short paragraph that says what the page helps the reader do.
+3. TOC on long pages.
+4. Main sections ordered from common workflow to advanced detail.
+5. Related links or next steps at the end.
+
+Keep prose direct. Avoid marketing copy when the page is operational documentation.
+
+## 4. Add Directives For Structure
+
+Use directives to make the document easier to scan:
+
+- Use callouts for risk, caveats, and important context.
+- Use steps for sequential procedures.
+- Use cards for choice sets, related pages, or capability summaries.
+- Use tabs for equivalent alternatives.
+- Use details for optional information that would interrupt the main path.
+
+Do not wrap every paragraph in a directive. The base format is still Markdown.
+
+## 5. Audit For Drift
+
+During a docs audit, verify:
+
+- option names and default values
+- import paths and exported symbols
+- directive names and attributes
+- command names and flags
+- file paths and route paths
+- warnings, limitations, and migration behavior
+
+Update docs when they differ from the implementation, even if the drift is small.

package/skills/payload-markdown/codex/reference/formatting.md

@@ -0,0 +1,81 @@
+# Formatting Guidance
+
+## Frontmatter
+
+When the docs system supports frontmatter, keep it simple and scalar-first:
+
+```yaml
+---
+title: Installation
+navTitle: Install
+description: Install and configure the package.
+order: 20
+status: published
+tags:
+  - getting-started
+  - installation
+---
+```
+
+Use only fields that the target docs system supports. Do not invent navigation or publishing fields.
+
+## Page Structure
+
+- Use exactly one H1.
+- Start with a short summary paragraph.
+- Use H2 for major tasks and H3 for subsections.
+- Avoid skipping heading levels unless the surrounding docs already do.
+- Put the TOC after the intro on long pages.
+
+## Links
+
+- Use root-relative internal links inside a docs set, such as `/configuration/code-blocks`.
+- Do not link to `.md` source paths unless documenting repository internals.
+- Use external URLs only when the reader must leave the docs set.
+- Prefer descriptive link text over "click here".
+
+## Code And Markdown Examples
+
+Use language-tagged fences:
+
+````md
+```ts
+payloadMarkdown({
+  collections: {
+    posts: true,
+  },
+})
+```
+````
+
+When documenting Markdown that contains fenced code blocks, make the outer fence longer than the inner fence:
+
+`````md
+````md
+:::steps
+
+### Install
+
+```bash
+pnpm add package-name
+```
+
+:::
+````
+`````
+
+## Prose Style
+
+- Prefer direct instructions.
+- Use present tense for current behavior.
+- Use "preferred" or "legacy" instead of implying older syntax is broken when it remains supported.
+- Name defaults explicitly when users depend on them.
+- Keep examples complete enough to copy.
+
+## What To Avoid
+
+- MDX imports or JSX components unless the target project explicitly supports MDX.
+- Raw HTML widgets for layout.
+- Runtime Tailwind classes in authored Markdown.
+- Unsupported directive names.
+- Placeholder claims such as "fully customizable" without naming the customization surface.