boxel-flavored-markdown

Files (7)

• SKILL.md
• authoring-notes.md · references/
• base-syntax.md · references/
• bfm-extensions-beyond-commonmarkgfm.md · references/
• card-directives-the-boxel-extension.md · references/
• quick-reference.md · references/
• where-bfm-is-used.md · references/

SKILL.md (first lines)

# 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

From cardstack/boxel-skills, MIT.

More from cardstack/boxel-skills