@valkyrianlabs/payload-markdown 1.3.4 → 1.4.1

package/skills/payload-markdown/claude/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/claude/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/claude/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/claude/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/claude/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/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.