@valkyrianlabs/payload-markdown 1.4.0 → 1.4.1

package/README.md

@@ -1,4 +1,4 @@
-![@valkyrianlabs/payload-markdown](https://docs-media.valkyrianlabs.com/payload-markdown_v1.3_release_banner.png)
+![@valkyrianlabs/payload-markdown](https://docs-media.valkyrianlabs.com/%40valkyrianlabspayload-markdown_v1.4.0-release-banner.png)
 
 [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/valkyrianlabs/payload-markdown/deploy.yml)](https://github.com/valkyrianlabs/payload-markdown/actions)
  

package/dist/types.d.ts

@@ -70,7 +70,7 @@ export interface PayloadMarkdownConfig {
     config?: ConfigOptions;
     /**
      * Enable or disable plugin
-     * @default false
+     * @default true
      */
     enabled?: boolean;
     /**

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types.ts"],"sourcesContent":["import type { CollectionSlug, TextField } from 'payload'\n\nimport type {\n  MarkdownCodeConfig,\n  MarkdownConfig,\n  MarkdownDirectiveThemes,\n  PayloadMarkdownIconsConfig,\n} from './types/core.js'\n\nexport type DualMarkdownFieldConfig = {\n  blocks?: MarkdownConfig\n  field?: MarkdownConfig\n}\n\nexport type ConfigOptions = DualMarkdownFieldConfig | MarkdownConfig\n\nexport type MarkdownFieldOptions = {\n  admin?: Partial<TextField['admin']>\n  defaultValue?: string\n  label?: string\n  localized?: boolean\n  name?: string\n  required?: boolean\n}\n\nexport type PayloadMarkdownCollectionConfig = {\n  /**\n   * Code fence / Shiki rendering options for markdown in this collection.\n   */\n  code?: MarkdownCodeConfig\n\n  /**\n   * Styling options for markdown fields added to the collection, and/or markdown fields added within blocks to the collection.\n   */\n  config?: ConfigOptions\n\n  /**\n   * Options for the markdown field.\n   */\n  field?: Omit<MarkdownFieldOptions, 'name'>\n\n  /**\n   * The name of the markdown field to add to the collection. Defaults to 'content'.\n   */\n  fieldName?: string\n\n  /**\n   * Whether to add a standalone markdown field to the collection.\n   *\n   * If not specified, this is inferred automatically:\n   * - `true` when the collection does not contain any `blocks` fields\n   * - `false` when the collection does contain `blocks` fields\n   */\n  installField?: boolean\n\n  /**\n   * Whether to install the markdown block into any `blocks` fields in the collection.\n   *\n   * If not specified, this is inferred automatically:\n   * - `true` when the collection contains one or more `blocks` fields\n   * - `false` when the collection does not contain any `blocks` fields\n   *\n   * Note: You must still add the MarkdownBlockComponent to your RenderBlocks.tsx\n   * or equivalent for the block to render properly.\n   */\n  installIntoBlocks?: boolean\n\n  /**\n   * Directive theme registry extensions for markdown in this collection.\n   */\n  themes?: MarkdownDirectiveThemes\n}\n\nexport interface PayloadMarkdownConfig {\n  /**\n   * Code fence / Shiki rendering options.\n   */\n  code?: MarkdownCodeConfig\n\n  /**\n   * Add markdown field to collections.\n   * Set to `true` to add a field with default options, or an object to configure the field.\n   */\n  collections?: Partial<Record<CollectionSlug, PayloadMarkdownCollectionConfig | true>>\n\n  /**\n   * Add a global for markdown block settings, which can be used to provide default configuration values for all markdown in the project.\n   */\n  config?: ConfigOptions\n\n  /**\n   * Enable or disable plugin\n   * @default false\n   */\n  enabled?: boolean\n\n  /**\n   * Local SVG icon pack configuration for markdown directives.\n   */\n  icons?: PayloadMarkdownIconsConfig\n\n  /**\n   * Directive theme registry extensions.\n   */\n  themes?: MarkdownDirectiveThemes\n}\n"],"names":[],"mappings":"AAyEA,WAgCC"}
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["import type { CollectionSlug, TextField } from 'payload'\n\nimport type {\n  MarkdownCodeConfig,\n  MarkdownConfig,\n  MarkdownDirectiveThemes,\n  PayloadMarkdownIconsConfig,\n} from './types/core.js'\n\nexport type DualMarkdownFieldConfig = {\n  blocks?: MarkdownConfig\n  field?: MarkdownConfig\n}\n\nexport type ConfigOptions = DualMarkdownFieldConfig | MarkdownConfig\n\nexport type MarkdownFieldOptions = {\n  admin?: Partial<TextField['admin']>\n  defaultValue?: string\n  label?: string\n  localized?: boolean\n  name?: string\n  required?: boolean\n}\n\nexport type PayloadMarkdownCollectionConfig = {\n  /**\n   * Code fence / Shiki rendering options for markdown in this collection.\n   */\n  code?: MarkdownCodeConfig\n\n  /**\n   * Styling options for markdown fields added to the collection, and/or markdown fields added within blocks to the collection.\n   */\n  config?: ConfigOptions\n\n  /**\n   * Options for the markdown field.\n   */\n  field?: Omit<MarkdownFieldOptions, 'name'>\n\n  /**\n   * The name of the markdown field to add to the collection. Defaults to 'content'.\n   */\n  fieldName?: string\n\n  /**\n   * Whether to add a standalone markdown field to the collection.\n   *\n   * If not specified, this is inferred automatically:\n   * - `true` when the collection does not contain any `blocks` fields\n   * - `false` when the collection does contain `blocks` fields\n   */\n  installField?: boolean\n\n  /**\n   * Whether to install the markdown block into any `blocks` fields in the collection.\n   *\n   * If not specified, this is inferred automatically:\n   * - `true` when the collection contains one or more `blocks` fields\n   * - `false` when the collection does not contain any `blocks` fields\n   *\n   * Note: You must still add the MarkdownBlockComponent to your RenderBlocks.tsx\n   * or equivalent for the block to render properly.\n   */\n  installIntoBlocks?: boolean\n\n  /**\n   * Directive theme registry extensions for markdown in this collection.\n   */\n  themes?: MarkdownDirectiveThemes\n}\n\nexport interface PayloadMarkdownConfig {\n  /**\n   * Code fence / Shiki rendering options.\n   */\n  code?: MarkdownCodeConfig\n\n  /**\n   * Add markdown field to collections.\n   * Set to `true` to add a field with default options, or an object to configure the field.\n   */\n  collections?: Partial<Record<CollectionSlug, PayloadMarkdownCollectionConfig | true>>\n\n  /**\n   * Add a global for markdown block settings, which can be used to provide default configuration values for all markdown in the project.\n   */\n  config?: ConfigOptions\n\n  /**\n   * Enable or disable plugin\n   * @default true\n   */\n  enabled?: boolean\n\n  /**\n   * Local SVG icon pack configuration for markdown directives.\n   */\n  icons?: PayloadMarkdownIconsConfig\n\n  /**\n   * Directive theme registry extensions.\n   */\n  themes?: MarkdownDirectiveThemes\n}\n"],"names":[],"mappings":"AAyEA,WAgCC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valkyrianlabs/payload-markdown",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Structured Markdown editing and rendering for Payload CMS with CodeMirror, Shiki, directives, themes, and server-first output.",
   "repository": {
     "url": "https://github.com/valkyrianlabs/payload-markdown"
@@ -32,7 +32,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "scripts": {
     "build": "pnpm copyfiles && pnpm build:types && pnpm build:swc",

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

@@ -0,0 +1,56 @@
+---
+name: payload-markdown
+description: Write elegant automated documentation with @valkyrianlabs/payload-markdown. Use when authoring, rewriting, auditing, or structuring docs with 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 Claude variant at `skills/payload-markdown/claude`. 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 when local shell access is available.
+
+## 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/claude/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/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.