@valkyrianlabs/payload-markdown 1.3.4 → 1.4.1

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:]))