Directives

Directives are Markdown primitives powered by the plugin directive registry. They keep content portable while giving the renderer enough structure for components such as callouts, details, tables of contents, steps, cards, buttons, tabs, sections, columns, and cells.

Public Directives

• :::callout
• :::details
• :::toc
• :::steps
• :::cards
• :::card
• ::button
• :::buttons
• :::tabs
• :::tab
• :::section
• :::2col
• :::3col
• :::cell

Basic Syntax

1:::callout[Read this first]{variant="warning"}2Content stays Markdown.3:::

Use [Label] for visible directive titles, and put attributes in braces. Expanded multiline attributes are preferred when a directive has more than one or two attributes:

1:::card[Markdown Field]{2  href="/getting-started/fields-and-blocks"3  theme="cyan"4}5Portable Markdown content.6:::

The older title="" form remains valid for existing Markdown, but snippets and docs prefer [Label].

Quoted values are supported. Boolean-style attributes are supported where a directive defines them, such as open="true" on details, numbered on card steps, or disabled on a tab.

Rendering Guarantees

• Directives render server-side.
• Directives do not require client hydration except for progressive tab and copy-button behavior.
• Nested Markdown remains Markdown.
• Unknown or malformed attributes warn where possible and fall back safely.
• Stable selectors are emitted for testing and styling, such as data-directive, data-theme, and vl-md-* classes.

Markdown-In-Markdown Examples

Use four backticks when documenting Markdown that itself contains fenced code blocks:

1````md2:::steps{3  variant="cards"4  stepTheme="glass"5}6 7### Install8 9```bash10pnpm add @valkyrianlabs/payload-markdown11```12 13### Configure14 15:::callout[Keep config in source]{variant="tip"}16Authors select themes by name. They do not need to write Tailwind classes.17:::18 19:::20````

The outer fence shows the literal Markdown. The inner fence remains part of the example content.

Heading Anchors

Headings render with deterministic IDs:

1## Install2 3## Install

Conceptual output:

1<h2 id="install">Install</h2>2<h2 id="install-1">Install</h2>

The table of contents directive uses those same heading IDs.

Directive Pages