Badges

Use ::badge leaf directives for individual Shields images and :::badges to group them.

1:::badges2::badge[npm]{3  type="npm"4  target="version"5  package="@valkyrianlabs/payload-markdown"6  href="https://www.npmjs.com/package/@valkyrianlabs/payload-markdown"7}8:::

::badge renders an img from https://img.shields.io. When href is present, the renderer wraps the image in an anchor. Click behavior uses that anchor wrapper; the directive does not use Shields' link query parameter.

::badge

Common attributes:

• [Label]: default image alt text
• alt: overrides the label-derived image alt text
• href: optional link target
• newTab: adds target="_blank" and rel="noopener noreferrer" when true
• style, logo, logoColor, logoSize, label, labelColor, color, and cacheSeconds: passed through to Shields as encoded query attributes

Curated resolvers:

• type="static" with label, message, and color
• type="npm" with target="version", target="downloads", or target="license" and package
• type="npm" target="downloads" also accepts interval; default is dw
• type="github" target="workflow" with repo and workflow
• type="github" with target="release", target="license", or target="stars" and repo
• type="debian" target="version" with package
• type="apt" is an alias for type="debian"

1::badge[build]{2  type="github"3  target="workflow"4  repo="valkyrianlabs/payload-markdown"5  workflow="deploy.yml"6  href="https://github.com/valkyrianlabs/payload-markdown/actions"7}

1::badge[downloads]{2  type="npm"3  target="downloads"4  package="@valkyrianlabs/payload-markdown"5  interval="dm"6}

1::badge[debian]{2  type="debian"3  target="version"4  package="curl"5}

1::badge[static]{2  type="static"3  label="docs"4  message="ready"5  color="0ea5e9"6}

Escape Hatches

Use path for a Shields path that is not covered by the curated resolver map:

1::badge[coverage]{2  path="badge/coverage-95%25-brightgreen"3  style="flat-square"4}

A path copied from shields.io is usually percent-encoded already (95%25); you can paste it as is or write the raw text (95%). Both render the same badge. Segments are encoded once, and paths that decode to .. or control characters are rejected.

Use src only for full Shields URLs. The renderer rejects non-https://img.shields.io hosts.

1::badge[custom]{2  src="https://img.shields.io/badge/custom-badge-blue"3}

:::badges

Attributes:

• align: left, center, or right
• gap: sm, md, or lg
• wrap: true or false

Defaults:

• align="left"
• gap="md"
• wrap="true"

1:::badges{2  align="center"3  gap="md"4  wrap=true5}6::badge[npm]{7  type="npm"8  target="version"9  package="@valkyrianlabs/payload-markdown"10}11::badge[license]{12  type="npm"13  target="license"14  package="@valkyrianlabs/payload-markdown"15}16:::