@valkyrianlabs/payload-markdown 1.4.0 → 1.4.1

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.

package/skills/payload-markdown/codex/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/codex/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/codex/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:]))