Buttons

Use ::button leaf directives for link buttons and :::buttons container directives for button groups.

1::button[Home]{2  href="/home"3  icon="@fa-duotone/home"4}

::button is the real Markdown directive. The editor may offer autocomplete shortcuts such as ::button_icon or ::button_full, but those are snippet variants only. Selecting them inserts canonical ::button[...] Markdown; writing ::button_icon in source is treated as an unknown directive.

::button

Attributes:

• href: required link target
• variant: primary, secondary, outline, ghost, or link
• size: sm, md, or lg
• icon: local icon reference such as @fa-duotone/home, optionally with its own palette: @fa-brands/ubuntu palette=ubuntu
• palette: colour palette for the button: fill from background, label from color, border from border (see Palettes)
• iconPalette: palette for the icon when it sets none
• iconPosition: left or right
• newTab: open href in a new tab when true
• ariaLabel: accessible label for icon-only buttons

Defaults:

• variant="primary"
• size="md"
• iconPosition="left"
• newTab="false"

Buttons render as anchors. When newTab is true, the renderer adds target="_blank" and rel="noopener noreferrer".

1::button[GitHub]{2  href="https://github.com/valkyrianlabs"3  icon="@brand/github"4  newTab=true5  variant="secondary"6}

Icon-only buttons require ariaLabel:

1::button[]{2  href="/settings"3  icon="@fa-duotone/gear"4  ariaLabel="Open settings"5}

:::buttons

Attributes:

• align: left, center, or right
• stack: mobile, always, or never
• gap: sm, md, or lg

Defaults:

• align="left"
• stack="mobile"
• gap="md"

1:::buttons{2  align="center"3  stack="mobile"4  gap="md"5}6::button[Get Started]{7  href="/docs"8  variant="primary"9  icon="@fa-duotone/rocket"10}11 12::button[GitHub]{13  href="https://github.com/valkyrianlabs"14  variant="secondary"15  icon="@brand/github"16  newTab=true17}18:::

:::buttons is intended for buttons, but non-button Markdown children render normally.

Icons

Button icons come from the local SVG icon packs configured in payloadMarkdown({ icons }). Markdown references use @pack/name; .svg is optional in source and omitted internally.

1::button[Docs]{2  href="/docs"3  icon="@fa-duotone/book-open"4}5 6::button[GitHub]{7  href="https://github.com/valkyrianlabs"8  icon="@brand/social/github"9  iconPosition="right"10}

Icon refs must stay within a configured pack. Unknown packs, missing SVG files, malformed refs, traversal with .., backslashes, and non-SVG targets produce diagnostics and render the button without the icon.