@valkyrianlabs/payload-markdown 1.3.4 → 1.4.0

package/README.md

@@ -12,7 +12,7 @@
 
 Structured Markdown editing and rendering for Payload CMS.
 
-`@valkyrianlabs/payload-markdown` gives Payload a Markdown-first authoring system with a CodeMirror editor, Shiki-powered code blocks, registry-backed directives, named themes, tabs, cards, table-of-contents generation, autocomplete, diagnostics, and server-first rendering.
+`@valkyrianlabs/payload-markdown` gives Payload a Markdown-first authoring system with a CodeMirror editor, Shiki-powered code blocks, registry-backed directives, local SVG icon packs, buttons, cards, table-of-contents generation, autocomplete, diagnostics, and server-first rendering.
 
 No bloated rich text editor.  
 No JSON-shaped content prison.  
@@ -20,6 +20,8 @@ No MDX ceremony for common docs/blog layouts.
 
 Just portable Markdown that renders like a real system.
 
+Payload Markdown now feels much closer to a Markdown-native design system: readable `[Title]` directive labels, expanded multiline args, local icon packs, button primitives, smarter autocomplete, richer card linking, and editor readability aids without giving up portable Markdown.
+
 ---
 
 ## Install
@@ -46,9 +48,9 @@ This plugin takes the third path:
 - Markdown stays the source of truth
 - structure lives directly in the content
 - rendering is production-ready by default
-- directives provide layout without turning content into a page-builder blob
+- directives provide layout, buttons, cards, and common calls to action without turning content into a page-builder blob
 - themes provide clean visual control without runtime Tailwind roulette
-- autocomplete and diagnostics make authoring fast instead of fussy
+- autocomplete, syntax highlighting, closing labels, and diagnostics make authoring fast instead of fussy
 
 **Write fast. Render clean. Stay in control.**
 
@@ -61,18 +63,61 @@ This plugin takes the third path:
 - **Editor UX** — CodeMirror-powered editing
 - **Code rendering** — Shiki-powered highlighting
 - **Server-first output** — clean rendering without client ceremony
-- **Structured directives** — callouts, details, TOCs, steps, cards, tabs, and layouts
-- **Autocomplete** — directive snippets and placeholders
+- **Structured directives** — callouts, details, TOCs, steps, cards, buttons, tabs, and layouts
+- **Buttons** — `::button` leaf directives and `:::buttons` groups
+- **Icon packs** — local SVG packs referenced as `@pack/name`
+- **Autocomplete** — directive snippets, placeholders, and editor-only snippet variants
 - **Diagnostics** — lightweight authoring warnings
 - **Heading anchors** — automatic IDs and table-of-contents support
 - **Themes** — themeable directive output with stable hooks
+- **Card links** — `linkScope` and `newTab` controls for card and cards layouts
 - **Scoped config** — global and collection-level overrides
 - **Portable storage** — clean Markdown source
 - **AI-friendly workflow** — content that agents and humans can edit sanely
 
-![Payload Markdown v1.3 directive preview](https://docs-media.valkyrianlabs.com/payload-markdown_v1.3_new_directives_example_1.png)
+![Payload Markdown directive preview](https://docs-media.valkyrianlabs.com/payload-markdown_v1.3_new_directives_example_1.png)
+
+`payload-markdown` renders structured Markdown directly inside the Payload admin preview, including callouts, details, TOCs, steps, cards, buttons, tabs, themes, icons, and code blocks — without turning your content into JSON-shaped sludge.
+
+---
+
+## v1.4 authoring primitives
+
+New examples prefer labels for visible titles and expanded attrs for anything non-trivial:
+
+```md
+:::card[Fast Setup]{
+  href="/getting-started/installation"
+  linkScope="title"
+  icon="@fa-duotone/bolt"
+}
+Install, configure, ship.
+
+:::buttons{
+  align="center"
+  stack="mobile"
+  gap="md"
+}
+::button[Read Docs]{
+  href="/docs"
+  variant="primary"
+  icon="@fa-duotone/book-open"
+}
+
+::button[GitHub]{
+  href="https://github.com/valkyrianlabs/payload-markdown"
+  variant="secondary"
+  icon="@brand/github"
+  newTab=true
+}
+:::
+
+:::
+```
+
+The older `title=""` form remains compatible, but `[Title]` keeps visible content out of the argument list. Card and cards directives support scoped linking through `linkScope`; use `linkScope="title"` when a card body contains buttons or links.
 
-`payload-markdown` renders structured Markdown directly inside the Payload admin preview, including callouts, details, TOCs, steps, cards, tabs, themes, and code blocks — without turning your content into JSON-shaped sludge.
+Editor completion can expose shortcuts such as `::button`, `::button_icon`, and `::button_full`, but generated Markdown always uses the canonical `::button` directive. Syntax highlighting now distinguishes directive names, labels, arg names, arg values, and leaf-vs-container directives, while closing labels make nested `:::` blocks easier to scan.
 
 ---
 
@@ -86,6 +131,8 @@ Payload Markdown supports structured directives for real content layouts:
 - `:::steps`
 - `:::cards`
 - `:::card`
+- `::button`
+- `:::buttons`
 - `:::tabs`
 - `:::tab`
 - `:::section`
@@ -113,7 +160,7 @@ Themes can be configured globally or scoped per collection, then selected direct
 
 Stable classes and data attributes are emitted for overrides, including `data-directive`, `data-theme`, and `vl-md-*` hook classes.
 
-[Theme documentation →](https://docs.valkyrianlabs.com/plugins/payload-markdown/configuration/themes)
+[Theme documentation →](https://docs.valkyrianlabs.com/plugins/payload-markdown/configuration/directive-themes)
 
 ---
 
@@ -133,7 +180,7 @@ Migration mapping:
 - `config.options.enhancedCodeBlocks` → `code.enhanced`
 - `config.fullBleedCode` → `code.fullBleed`
 
-[Code block documentation →](https://docs.valkyrianlabs.com/plugins/payload-markdown/configuration/code)
+[Code block documentation →](https://docs.valkyrianlabs.com/plugins/payload-markdown/configuration/code-blocks)
 
 ---
 
@@ -152,7 +199,7 @@ The full setup guide covers:
 - themes
 - code block options
 
-[Quick start →](https://docs.valkyrianlabs.com/plugins/payload-markdown/getting-started)
+[Quick start →](https://docs.valkyrianlabs.com/plugins/payload-markdown/getting-started/installation)
 
 ---
 
@@ -161,16 +208,18 @@ The full setup guide covers:
 The editor is built on CodeMirror and includes:
 
 - Markdown syntax highlighting
-- directive autocomplete
-- directive snippets
+- directive autocomplete, including snippet variants such as `::button_icon`
+- directive snippets with canonical Markdown output
 - snippet placeholders/tabstops
 - theme-aware attribute suggestions
+- highlighting for directive labels and expanded arg blocks
+- visual closing labels for nested directive blocks
 - lightweight diagnostics for malformed directives
 - warnings for unknown directives, invalid variants, invalid themes, malformed attrs, and common structural issues
 
 The goal is simple: author Markdown like text, but get enough tooling that complex docs stay pleasant.
 
-[Editor documentation →](https://docs.valkyrianlabs.com/plugins/payload-markdown/editor)
+[Editor documentation →](https://docs.valkyrianlabs.com/plugins/payload-markdown/authoring/editor)
 
 ---
 
@@ -188,7 +237,7 @@ Theme class strings defined in your app config should also live in scanned sourc
 
 Runtime arbitrary Tailwind classes inside CMS-authored Markdown are not the recommended styling path. Use directive `theme="..."` values and configure named themes in source.
 
-[Tailwind setup →](https://docs.valkyrianlabs.com/plugins/payload-markdown/getting-started/tailwind)
+[Tailwind setup →](https://docs.valkyrianlabs.com/plugins/payload-markdown/configuration/styling)
 
 ---
 

package/dist/components/MarkdownRenderer/index.css

@@ -66,4 +66,154 @@ pre.shiki.md-code-enhanced code span.md-line .md-empty-line {
   pointer-events: none;
 }
 
+.pmd-button {
+  --pmd-button-bg: rgb(8 145 178);
+  --pmd-button-border: rgb(8 145 178);
+  --pmd-button-color: rgb(255 255 255);
+  --pmd-button-hover-bg: rgb(6 182 212);
+  --pmd-button-hover-border: rgb(6 182 212);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  border: 1px solid var(--pmd-button-border);
+  border-radius: 0.5rem;
+  background: var(--pmd-button-bg);
+  color: var(--pmd-button-color);
+  font-weight: 600;
+  line-height: 1;
+  text-decoration: none;
+  transition: background-color 160ms ease, border-color 160ms ease, color 160ms ease, opacity 160ms ease;
+}
+.pmd-button:hover {
+  background: var(--pmd-button-hover-bg);
+  border-color: var(--pmd-button-hover-border);
+  color: var(--pmd-button-color);
+}
+.pmd-button:focus-visible {
+  outline: 2px solid rgb(103, 232, 249);
+  outline-offset: 2px;
+}
+
+.pmd-button--secondary {
+  --pmd-button-bg: rgb(255 255 255 / 0.08);
+  --pmd-button-border: rgb(255 255 255 / 0.14);
+  --pmd-button-color: rgb(244 244 245);
+  --pmd-button-hover-bg: rgb(255 255 255 / 0.12);
+  --pmd-button-hover-border: rgb(255 255 255 / 0.2);
+}
+
+.pmd-button--outline {
+  --pmd-button-bg: transparent;
+  --pmd-button-border: rgb(8 145 178 / 0.65);
+  --pmd-button-color: rgb(103 232 249);
+  --pmd-button-hover-bg: rgb(8 145 178 / 0.12);
+  --pmd-button-hover-border: rgb(6 182 212);
+}
+
+.pmd-button--ghost {
+  --pmd-button-bg: transparent;
+  --pmd-button-border: transparent;
+  --pmd-button-color: rgb(103 232 249);
+  --pmd-button-hover-bg: rgb(255 255 255 / 0.08);
+  --pmd-button-hover-border: transparent;
+}
+
+.pmd-button--link {
+  --pmd-button-bg: transparent;
+  --pmd-button-border: transparent;
+  --pmd-button-color: rgb(103 232 249);
+  --pmd-button-hover-bg: transparent;
+  --pmd-button-hover-border: transparent;
+  padding-right: 0;
+  padding-left: 0;
+  text-decoration: underline;
+  text-underline-offset: 0.22em;
+}
+
+.pmd-button--sm {
+  min-height: 2rem;
+  padding: 0.45rem 0.75rem;
+  font-size: 0.875rem;
+}
+
+.pmd-button--md {
+  min-height: 2.5rem;
+  padding: 0.6rem 0.95rem;
+  font-size: 0.9375rem;
+}
+
+.pmd-button--lg {
+  min-height: 3rem;
+  padding: 0.75rem 1.15rem;
+  font-size: 1rem;
+}
+
+.pmd-button__icon {
+  display: inline-flex;
+  width: 1em;
+  height: 1em;
+  flex: 0 0 auto;
+  align-items: center;
+  justify-content: center;
+}
+.pmd-button__icon svg,
+.pmd-button__icon path {
+  vector-effect: non-scaling-stroke;
+}
+
+.pmd-button__icon--right {
+  order: 2;
+}
+
+.pmd-buttons {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+}
+
+.pmd-buttons--align-left {
+  justify-content: flex-start;
+}
+
+.pmd-buttons--align-center {
+  justify-content: center;
+}
+
+.pmd-buttons--align-right {
+  justify-content: flex-end;
+}
+
+.pmd-buttons--stack-mobile {
+  flex-direction: column;
+  align-items: stretch;
+}
+@media (min-width: 640px) {
+  .pmd-buttons--stack-mobile {
+    flex-direction: row;
+    align-items: center;
+  }
+}
+
+.pmd-buttons--stack-always {
+  flex-direction: column;
+  align-items: stretch;
+}
+
+.pmd-buttons--stack-never {
+  flex-direction: row;
+}
+
+.pmd-buttons--gap-sm {
+  gap: 0.5rem;
+}
+
+.pmd-buttons--gap-md {
+  gap: 0.75rem;
+}
+
+.pmd-buttons--gap-lg {
+  gap: 1rem;
+}
+
 /*# sourceMappingURL=index.css.map */

package/dist/components/MarkdownRenderer/index.scss

@@ -81,3 +81,161 @@ pre.shiki.md-code-enhanced {
     }
   }
 }
+
+.pmd-button {
+  --pmd-button-bg: rgb(8 145 178);
+  --pmd-button-border: rgb(8 145 178);
+  --pmd-button-color: rgb(255 255 255);
+  --pmd-button-hover-bg: rgb(6 182 212);
+  --pmd-button-hover-border: rgb(6 182 212);
+
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  border: 1px solid var(--pmd-button-border);
+  border-radius: 0.5rem;
+  background: var(--pmd-button-bg);
+  color: var(--pmd-button-color);
+  font-weight: 600;
+  line-height: 1;
+  text-decoration: none;
+  transition:
+    background-color 160ms ease,
+    border-color 160ms ease,
+    color 160ms ease,
+    opacity 160ms ease;
+
+  &:hover {
+    background: var(--pmd-button-hover-bg);
+    border-color: var(--pmd-button-hover-border);
+    color: var(--pmd-button-color);
+  }
+
+  &:focus-visible {
+    outline: 2px solid rgb(103 232 249);
+    outline-offset: 2px;
+  }
+}
+
+.pmd-button--secondary {
+  --pmd-button-bg: rgb(255 255 255 / 0.08);
+  --pmd-button-border: rgb(255 255 255 / 0.14);
+  --pmd-button-color: rgb(244 244 245);
+  --pmd-button-hover-bg: rgb(255 255 255 / 0.12);
+  --pmd-button-hover-border: rgb(255 255 255 / 0.2);
+}
+
+.pmd-button--outline {
+  --pmd-button-bg: transparent;
+  --pmd-button-border: rgb(8 145 178 / 0.65);
+  --pmd-button-color: rgb(103 232 249);
+  --pmd-button-hover-bg: rgb(8 145 178 / 0.12);
+  --pmd-button-hover-border: rgb(6 182 212);
+}
+
+.pmd-button--ghost {
+  --pmd-button-bg: transparent;
+  --pmd-button-border: transparent;
+  --pmd-button-color: rgb(103 232 249);
+  --pmd-button-hover-bg: rgb(255 255 255 / 0.08);
+  --pmd-button-hover-border: transparent;
+}
+
+.pmd-button--link {
+  --pmd-button-bg: transparent;
+  --pmd-button-border: transparent;
+  --pmd-button-color: rgb(103 232 249);
+  --pmd-button-hover-bg: transparent;
+  --pmd-button-hover-border: transparent;
+
+  padding-right: 0;
+  padding-left: 0;
+  text-decoration: underline;
+  text-underline-offset: 0.22em;
+}
+
+.pmd-button--sm {
+  min-height: 2rem;
+  padding: 0.45rem 0.75rem;
+  font-size: 0.875rem;
+}
+
+.pmd-button--md {
+  min-height: 2.5rem;
+  padding: 0.6rem 0.95rem;
+  font-size: 0.9375rem;
+}
+
+.pmd-button--lg {
+  min-height: 3rem;
+  padding: 0.75rem 1.15rem;
+  font-size: 1rem;
+}
+
+.pmd-button__icon {
+  display: inline-flex;
+  width: 1em;
+  height: 1em;
+  flex: 0 0 auto;
+  align-items: center;
+  justify-content: center;
+
+  svg,
+  path {
+    vector-effect: non-scaling-stroke;
+  }
+}
+
+.pmd-button__icon--right {
+  order: 2;
+}
+
+.pmd-buttons {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+}
+
+.pmd-buttons--align-left {
+  justify-content: flex-start;
+}
+
+.pmd-buttons--align-center {
+  justify-content: center;
+}
+
+.pmd-buttons--align-right {
+  justify-content: flex-end;
+}
+
+.pmd-buttons--stack-mobile {
+  flex-direction: column;
+  align-items: stretch;
+
+  @media (min-width: 640px) {
+    flex-direction: row;
+    align-items: center;
+  }
+}
+
+.pmd-buttons--stack-always {
+  flex-direction: column;
+  align-items: stretch;
+}
+
+.pmd-buttons--stack-never {
+  flex-direction: row;
+}
+
+.pmd-buttons--gap-sm {
+  gap: 0.5rem;
+}
+
+.pmd-buttons--gap-md {
+  gap: 0.75rem;
+}
+
+.pmd-buttons--gap-lg {
+  gap: 1rem;
+}

package/dist/core/plugins/rehypeResolveIcons.d.ts

@@ -0,0 +1,4 @@
+import type { Root } from 'hast';
+import type { Plugin } from 'unified';
+import type { MarkdownRenderConfig } from '../../types/core.js';
+export declare const rehypeResolveIcons: Plugin<[MarkdownRenderConfig?], Root>;

package/dist/core/plugins/rehypeResolveIcons.js

@@ -0,0 +1,27 @@
+import { visit } from 'unist-util-visit';
+import { resolvePayloadMarkdownIcon, validatePayloadMarkdownIconsConfig } from '../../icons/resolve.js';
+function isElement(node) {
+    return Boolean(node && typeof node === 'object' && 'type' in node && node.type === 'element');
+}
+function getStringProperty(node, name) {
+    const value = node.properties?.[name];
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+export const rehypeResolveIcons = (config = {})=>{
+    return (tree, file)=>{
+        for (const warning of validatePayloadMarkdownIconsConfig(config.icons))file.message(warning);
+        visit(tree, 'element', (node, index, parent)=>{
+            if (!isElement(node)) return;
+            if (node.tagName !== 'span') return;
+            const iconRef = getStringProperty(node, 'dataPmdIconRef');
+            if (!iconRef) return;
+            const className = Array.isArray(node.properties.className) ? node.properties.className.join(' ') : typeof node.properties.className === 'string' ? node.properties.className : 'pmd-icon';
+            const resolved = resolvePayloadMarkdownIcon(iconRef, config.icons, className);
+            for (const warning of resolved.warnings)file.message(warning);
+            if (!parent || typeof index !== 'number') return;
+            parent.children.splice(index, 1, ...resolved.nodes);
+        });
+    };
+};
+
+//# sourceMappingURL=rehypeResolveIcons.js.map

package/dist/core/plugins/rehypeResolveIcons.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/core/plugins/rehypeResolveIcons.ts"],"sourcesContent":["import type { Element, Root } from 'hast'\nimport type { Plugin } from 'unified'\n\nimport { visit } from 'unist-util-visit'\n\nimport type { MarkdownRenderConfig } from '../../types/core.js'\n\nimport {\n  resolvePayloadMarkdownIcon,\n  validatePayloadMarkdownIconsConfig,\n} from '../../icons/resolve.js'\n\nfunction isElement(node: unknown): node is Element {\n  return Boolean(\n    node && typeof node === 'object' && 'type' in node && (node as Element).type === 'element',\n  )\n}\n\nfunction getStringProperty(node: Element, name: string): string | undefined {\n  const value = node.properties?.[name]\n\n  return typeof value === 'string' && value.trim() ? value.trim() : undefined\n}\n\nexport const rehypeResolveIcons: Plugin<[MarkdownRenderConfig?], Root> = (\n  config: MarkdownRenderConfig = {},\n) => {\n  return (tree, file) => {\n    for (const warning of validatePayloadMarkdownIconsConfig(config.icons)) file.message(warning)\n\n    visit(tree, 'element', (node, index, parent) => {\n      if (!isElement(node)) return\n      if (node.tagName !== 'span') return\n\n      const iconRef = getStringProperty(node, 'dataPmdIconRef')\n      if (!iconRef) return\n\n      const className = Array.isArray(node.properties.className)\n        ? node.properties.className.join(' ')\n        : typeof node.properties.className === 'string'\n          ? node.properties.className\n          : 'pmd-icon'\n      const resolved = resolvePayloadMarkdownIcon(iconRef, config.icons, className)\n\n      for (const warning of resolved.warnings) file.message(warning)\n\n      if (!parent || typeof index !== 'number') return\n\n      parent.children.splice(index, 1, ...resolved.nodes)\n    })\n  }\n}\n"],"names":["visit","resolvePayloadMarkdownIcon","validatePayloadMarkdownIconsConfig","isElement","node","Boolean","type","getStringProperty","name","value","properties","trim","undefined","rehypeResolveIcons","config","tree","file","warning","icons","message","index","parent","tagName","iconRef","className","Array","isArray","join","resolved","warnings","children","splice","nodes"],"mappings":"AAGA,SAASA,KAAK,QAAQ,mBAAkB;AAIxC,SACEC,0BAA0B,EAC1BC,kCAAkC,QAC7B,yBAAwB;AAE/B,SAASC,UAAUC,IAAa;IAC9B,OAAOC,QACLD,QAAQ,OAAOA,SAAS,YAAY,UAAUA,QAAQ,AAACA,KAAiBE,IAAI,KAAK;AAErF;AAEA,SAASC,kBAAkBH,IAAa,EAAEI,IAAY;IACpD,MAAMC,QAAQL,KAAKM,UAAU,EAAE,CAACF,KAAK;IAErC,OAAO,OAAOC,UAAU,YAAYA,MAAME,IAAI,KAAKF,MAAME,IAAI,KAAKC;AACpE;AAEA,OAAO,MAAMC,qBAA4D,CACvEC,SAA+B,CAAC,CAAC;IAEjC,OAAO,CAACC,MAAMC;QACZ,KAAK,MAAMC,WAAWf,mCAAmCY,OAAOI,KAAK,EAAGF,KAAKG,OAAO,CAACF;QAErFjB,MAAMe,MAAM,WAAW,CAACX,MAAMgB,OAAOC;YACnC,IAAI,CAAClB,UAAUC,OAAO;YACtB,IAAIA,KAAKkB,OAAO,KAAK,QAAQ;YAE7B,MAAMC,UAAUhB,kBAAkBH,MAAM;YACxC,IAAI,CAACmB,SAAS;YAEd,MAAMC,YAAYC,MAAMC,OAAO,CAACtB,KAAKM,UAAU,CAACc,SAAS,IACrDpB,KAAKM,UAAU,CAACc,SAAS,CAACG,IAAI,CAAC,OAC/B,OAAOvB,KAAKM,UAAU,CAACc,SAAS,KAAK,WACnCpB,KAAKM,UAAU,CAACc,SAAS,GACzB;YACN,MAAMI,WAAW3B,2BAA2BsB,SAAST,OAAOI,KAAK,EAAEM;YAEnE,KAAK,MAAMP,WAAWW,SAASC,QAAQ,CAAEb,KAAKG,OAAO,CAACF;YAEtD,IAAI,CAACI,UAAU,OAAOD,UAAU,UAAU;YAE1CC,OAAOS,QAAQ,CAACC,MAAM,CAACX,OAAO,MAAMQ,SAASI,KAAK;QACpD;IACF;AACF,EAAC"}

package/dist/core/plugins/remarkButtonDirectives.d.ts

@@ -0,0 +1,4 @@
+import type { Root } from 'mdast';
+import type { Plugin } from 'unified';
+import type { MarkdownRenderConfig } from '../../types/core.js';
+export declare const remarkButtonDirectives: Plugin<[MarkdownRenderConfig?], Root>;