cardstack/boxel-skills/boxel-flavored-markdown

Boxel Flavored Markdown (BFM)

_BFM reference: render surfaces, base syntax, :card/::card directives, mermaid, math ($...$ / $$...$$), alerts, footnotes, and code highlighting._

BFM is the markdown dialect Boxel reads and writes. It extends CommonMark + GitHub Flavored Markdown with:

• Card directives (:card[URL], ::card[URL | spec]) for embedding cards
• Mermaid diagrams in fenced code blocks
• LaTeX math via $...$ / $$...$$ (KaTeX)
• GFM alerts (> [!NOTE], > [!WARNING], etc.)
• Footnotes, extended tables, heading IDs
• Monaco-powered syntax highlighting for fenced code blocks

Pair with

• `boxel-markdown-format` — when you're generating BFM as the output of a static markdown template.
• `boxel` — for the surrounding CardDef when the content is a card field: RichMarkdownField when it embeds cards (a plain MarkdownField never resolves :card[] directives).

Don't use for

• Plain CommonMark or GFM content with no Boxel-specific directives (no extra skill needed).
• HTML-emitting markdown (BFM is plain-text; the runtime renders it).

Sections (load on demand)

• references/where-bfm-is-used.md — Where BFM is used
• references/base-syntax.md — Base syntax
• references/bfm-extensions-beyond-commonmarkgfm.md — BFM extensions beyond CommonMark/GFM
• references/card-directives-the-boxel-extension.md — Card directives (the Boxel extension)
• references/authoring-notes.md — Authoring notes
• references/quick-reference.md — Quick reference