Markdown Icon Showcase

This page is a live demo, not just documentation. The site you are reading is built with Sarde, whose icon pipeline is powered by go-swarm-icons, so every icon below is inline SVG resolved and rendered by this library at build time. To wire the same :icon[...] syntax into your own Goldmark setup, see Goldmark Integration.

Basic syntax

Write :icon[name] anywhere in Markdown. Bare names resolve from the default set (Lucide); a set:name prefix targets a specific set.

1
:icon[rocket] :icon[heart] :icon[star] :icon[bell] :icon[settings]

Icons render as inline <svg> elements that inherit the surrounding text color via currentColor, so they recolor themselves to match their context automatically.

Icon sets

The same syntax reaches every set registered on the IconManager. This site bundles three:

In your own application the prefixes are whatever you register: a directory of custom SVGs, an Iconify JSON collection, or the Iconify API. See Working with Icon Sets.

Sizing

Set an explicit width; the height is derived from the icon's aspect ratio:

Transforms

rotate takes degrees; flip takes horizontal, vertical, or both:

Colors

Icons follow currentColor by default; the style attribute overrides it with any CSS color value:

1
:icon[star width="28" style="color: gold"]
2
:icon[settings width="28" style="color: dodgerblue"]

Colored icons work naturally as inline status markers:

Pass  ·  Fail  ·  Warn  ·  Info

Combined attributes

Size, color, rotation, and flips compose freely:

Inheriting context color

Because icons default to currentColor, they pick up the color of whatever contains them, no configuration needed:

Brand icons

A social-link row from the Simple Icons set:

A tech-stack row:

Accessibility

Icons are decorative by default (aria-hidden="true", not announced by screen readers). Provide title or aria-label to give an accessible name, which promotes the SVG to role="img":

• Decorative: :icon[star]
• Labeled: :icon[bell aria-label="Notifications"]
• Titled (tooltip + name): :icon[settings title="Settings"]

The library injects the ARIA attributes automatically. See Attribute Management.

Fallbacks

An unknown name renders the configured fallback icon instead of failing: :icon[definitely-not-an-icon] gives on this site. That behavior comes from FallbackIcon() on the manager; see Aliases & Fallbacks.

Under the hood

Every technique on this page maps to a library feature you configure once on the IconManager: providers give you the sets, the Goldmark extension gives you the syntax, attribute merging and ARIA injection handle the output, and the optional sprite collector deduplicates repeated icons into <symbol>/<use> references.