BFM v3 Syntax Guide

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

function greet(name) {
  return `Hello, ${name}!`;
}

| Feature   | Status  | Priority |
|:----------|:-------:|---------:|
| Auth      | Done    |     High |
| Dashboard | WIP     |   Medium |

> [!NOTE]
> Useful background information.

> [!WARNING]
> Something could go wrong.

> [!TIP]
> A helpful shortcut.

```mermaid
graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Ship it]
    B -->|No| D[Fix it]
```

> [!question] Can callouts fold?
> Yes they can!

> [!tip]- Collapsed by default
> Click to reveal.

> [!warning]+ Open but collapsible
> Can be folded shut.

```toc
style: nestedList
maxLevel: 3
```

```table-of-contents
style: nestedList
maxLevel: 3
```

---
title: My Document
tags:
  - project
  - active
aliases:
  - Alt Name
cssclasses:
  - wide-layout
date: 2026-04-03
---

```dataview
TABLE author, date, status
FROM #project
WHERE status != "done"
SORT date DESC
LIMIT 10
```

---
title: Q2 Market Report

adoptsFrom:                         # Card type (optional -- defaults to base document card)
  module: ./story
  name: Story

theme: ./Theme/literary-review      # Theme card reference

thumbnailURL: ./assets/hero.png     # Card preview image (overrides cardInfo.thumbnailURL)

fields:                             # Field schema (compact shorthand for %%%field blocks)
  status:
    type: StatusField
    from: ./story-fields
    default: draft
  total:
    type: NumberField
    from: ./fields
    expression: ROUND(.subtotal * 1.0825; 2)

renderers:                          # Map fenced languages to custom FieldDefs
  timeline:
    type: TimelineField
    from: ./timeline-widget
---

```mermaid           → built-in MermaidField
```csv               → built-in CsvTableField
```math              → built-in MathField
```slides            → built-in SlideField

---
renderers:
  mermaid:
    type: CustomDiagramField
    from: ./custom-diagram
  csv:
    type: SpreadsheetField
    from: ./spreadsheet
  timeline:
    type: TimelineField
    from: ./timeline-widget
  kanban:
    type: KanbanField
    from: ./kanban-board
  chart:
    type: ChartField
    from: ./chart-widget
  form:
    type: FormField
    from: ./form-builder
---
```timeline
- 2026-01: Project kickoff
- 2026-03: Alpha release
- 2026-06: Public launch
```

```kanban
## Backlog
- Design review
- API docs
## In Progress
- Parser implementation
## Done
- Spec draft
```

```chart
type: bar
data:
  labels: [Q1, Q2, Q3, Q4]
  values: [12, 19, 8, 15]
```

```form
fields:
  - name: email
    type: email
    required: true
  - name: message
    type: textarea
```

:::list
::card[./Cards/aero-stock | strip]
::card[./Cards/nvda-stock | strip]
::card[./Cards/tsla-stock | strip]
:::

:::grid[cols:3]
::card[./Cards/aero-stock]
::card[./Cards/nvda-stock]
::card[./Cards/tsla-stock]
:::

:::grid[cols:2 gap:1rem]
::card[./Cards/team-alice]
::card[./Cards/team-bob]
::card[./Cards/team-carol]
::card[./Cards/team-dan]
:::

:::list[query]
type: Project
filter:
  eq: { status: active }
sort:
  by: due-date
  direction: asc
limit: 10
:::

:::grid[cols:3 query]
type: TeamMember
filter:
  eq: { department: Engineering }
sort:
  by: name
:::

:::list[query]
type: StockTicker
expression: |
  . | select(.change > 0)
    | sort_by(-.change)
size: strip
:::

```mermaid              <-- visible, renders as diagram
graph TD; A --> B
```

%%author note%%         <-- hidden, comment (Obsidian)

%%%field approval-note  <-- hidden, structural metadata
adoptsFrom:
  module: ./fields
  name: StringField
value: Pending review
%%%

## Project Status

Status: :field[.status@edit]          <-- from containing card

Progress: ::field[#progress@edit]     <-- from local field

%%%field progress
adoptsFrom:
  module: ./story-fields
  name: ProgressField
value: 42
%%%

Note: :field[#approval-note@edit]     <-- from local field

%%%field approval-note
adoptsFrom:
  module: ./fields
  name: StringField
value: Pending review
%%%

%%%field total
adoptsFrom:
  module: ./fields
  name: NumberField
expression: ROUND(.subtotal * (1 + .taxRate); 2)
%%%

Total: :field[#total]

%%%field subtotal-with-tax
adoptsFrom:
  module: ./fields
  name: NumberField
expression: ROUND(.subtotal * (1 + .taxRate); 2)
%%%

%%%field grand-total
adoptsFrom:
  module: ./fields
  name: NumberField
expression: local("subtotal-with-tax") + .shipping
%%%

Grand total: :field[#grand-total]

%%%field line-item-list
adoptsFrom: { module: ./fields, name: StringField }
expression: |
  .line-items
  | map("- " + .description + " -- " + DOLLAR(.amount; 2))
  | join("\n")
%%%

## Line Items

::field[#line-item-list]

**Total: :field[.total | DOLLAR(.; 2)]**

%%%field invoice-rows
adoptsFrom: { module: ./fields, name: StringField }
expression: |
  .invoices
  | map("| " + .id + " | " + .client.name + " | " + DOLLAR(.amount; 2)
        + " | " + IF(.amount > 1000; "Large"; "Small") + " |")
  | join("\n")
%%%

| ID | Client | Amount | Size |
|----|--------|-------:|------|
::field[#invoice-rows]

Total invoices: :field[.invoices | length]
Sum: :field[.invoices | map(.amount) | add | DOLLAR(.; 2)]

:::list[query]
type: TeamMember
from: .team
size: strip
:::

%%%field subtotal
adoptsFrom: { module: ./fields, name: NumberField }
expression: |
  .line-items | map(.qty * .unit-price) | add
%%%

%%%field discount-amount
adoptsFrom: { module: ./fields, name: NumberField }
expression: |
  (.line-items | map(.qty * .unit-price) | add) as $sub
  | if $sub > 10000 then ROUND($sub * 0.10; 2)
    elif $sub > 5000 then ROUND($sub * 0.05; 2)
    else 0 end
%%%

%%%field tax
adoptsFrom: { module: ./fields, name: NumberField }
expression: ROUND((.subtotal - .discount-amount) * .tax-rate; 2)
%%%

%%%field total
adoptsFrom: { module: ./fields, name: NumberField }
expression: .subtotal - .discount-amount + .tax
%%%

%%%field discount-row
adoptsFrom: { module: ./fields, name: StringField }
expression: |
  if .discount-amount > 0 then
    "| Discount " + IF(.subtotal > 10000; "(10%)"; "(5%)")
    + " | -" + DOLLAR(.discount-amount; 2) + " |"
  else null end
%%%

%%%field notes-section
adoptsFrom: { module: ./fields, name: StringField }
expression: |
  if (.notes | length) > 0 then
    "### Notes\n\n"
    + (.notes | map("- " + .) | join("\n"))
  else null end
%%%

%%%field approval-notice
adoptsFrom: { module: ./fields, name: StringField }
expression: |
  if .total > 25000 then
    "> [!warning] This quote exceeds $25,000 and requires director sign-off."
  else null end
%%%

%%%table line-items
columns: "#, Description, Qty, Unit Price, Line Total"
from: .line-items
expression: |
  . | to_entries
  | map({
      "#": (.key + 1),
      Description: .value.description,
      Qty: .value.qty,
      "Unit Price": DOLLAR(.value.unit-price; 2),
      "Line Total": DOLLAR(.value.qty * .value.unit-price; 2)
    })
%%%

# Quote :field[.quote-number]

**Prepared for:** :field[.client.name]
**Date:** :field[.created | strftime("%B %d, %Y")]
**Valid until:** :field[.expires | strftime("%B %d, %Y")]

---
::table[line-items]

---
| | |
|:--|--:|
| Subtotal | :field[.subtotal | DOLLAR(.; 2)] |
::field[#discount-row]
| Tax (:field[.tax-rate * 100 | ROUND(.; 1)]%) | :field[.tax | DOLLAR(.; 2)] |
| **Total** | **:field[.total | DOLLAR(.; 2)]** |

::field[#notes-section]

::field[#approval-notice]

---
title: Welcome Email
adoptsFrom: { module: ./email-template, name: EmailTemplate }
---
%%%field plan-section
adoptsFrom: { module: ./fields, name: StringField }
expression: |
  if .recipient.plan == "pro" then
    "As a **Pro** member, you get access to:\n\n"
    + (.pro-features | map("- " + .name + " -- " + .description) | join("\n"))
  else
    "Check out our Pro plan for advanced features."
  end
%%%

Hi :field[.recipient.first-name],

Welcome to :field[.sender.company]! We're excited to have you.

::field[#plan-section]

Best,
:field[.sender.name]
:field[.sender.title] at :field[.sender.company]

---
title: Service Agreement
adoptsFrom: { module: ./contract, name: ServiceContract }
fields:
  effective-date: { type: DueDateField, from: ./fields, value: 2026-05-01 }
  term-months: { type: NumberField, from: ./fields, value: 12 }
  monthly-rate: { type: NumberField, from: ./fields, value: 15000 }
  total-value:
    type: NumberField
    from: ./fields
    expression: .term-months * .monthly-rate
---
# Service Agreement

This Agreement is entered into as of :field[.effective-date | strftime("%B %d, %Y")]
by and between **:field[.provider.legal-name]** ("Provider") and
**:field[.client.legal-name]** ("Client").

## 1. Services

Provider agrees to deliver the services described in Exhibit A
for a period of :field[.term-months] months at a rate of
:field[.monthly-rate | DOLLAR(.; 0)] per month, totaling
:field[.total-value | DOLLAR(.; 0)].

## 2. Authorized Contacts

| Role | Name | Email |
|------|------|-------|
| Client Contact | :field[.client.contact-name] | :field[.client.contact-email] |
| Provider Lead | :field[.provider.lead-name] | :field[.provider.lead-email] |

Signed: :field[.client.signatory@edit]    Date: :field[.sign-date@edit]

%%%field risk-warning
adoptsFrom: { module: ./fields, name: StringField }
expression: |
  if .status == "at-risk" then
    "> [!warning] This project is at risk.\n> Review the timeline and escalate."
  else null end
%%%

%%%field completion-notice
adoptsFrom: { module: ./fields, name: StringField }
expression: |
  if .progress >= 100 then
    "> [!success] Project complete!"
  else null end
%%%

::field[#risk-warning]
::field[#completion-notice]

%%%field margin-status
adoptsFrom: { module: ./fields, name: StringField }
expression: |
  if .margin > 30 then
    "Healthy margins at " + (.margin | tostring) + "%."
  else
    "> [!warning] Margins below 30% -- review expenses."
  end
%%%

::field[#margin-status]

%%%table charges
columns: Item, Qty, Amount
from: .lineItems
map: {Item: .item, Qty: .qty, Amount: DOLLAR(.amount; 2)}
%%%

::table[charges]

# Mode 1: Field (contained in this document)
# No ID = anonymous field, rendered in-place

```mermaid
graph TD
    A --> B --> C
```

# Mode 2: Field with ID (referenceable, in containedFields)

```mermaid diagram-flow
graph TD
    A --> B --> C
```
::field[.diagram-flow]          <!-- render it elsewhere in the doc -->

# Mode 3: Card (standalone, has its own URL)

::card[./Diagrams/architecture-flow]

%%%field profit
type: NumberField
from: ./fields
expression: |
  .revenue - .expenses
%%%

%%%table breakdown
expression: |
  .line-items
  | map({
      Item: .label,
      Amount: DOLLAR(.amount; 2),
      Pct: (ROUND(.amount / .subtotal * 100; 1) | tostring) + "%"
    })
  | sort_by(.Amount)
columns: Item, Amount, Pct
%%%

```dataview
{
  "filter": {
    "type": "StockTicker",
    "every": [{ "eq": { "sector": "Technology" } }]
  },
  "sort": [{ "by": "price", "direction": "desc" }],
  "page": { "size": 10 }
}
```

@agent:claude-code[model: opus, env: claude-code, as: @chris]
@agent:reviewer[env: matrix, as: self, requested-by: @chris]
@agent:moderator[env: matrix, as: self, role: moderator]
@agent:browser[env: browser, mode: suggest]

The largest technology IPO since Arm Holdings.
{>> Is Arm still the right benchmark? --@bob}
{>> Reddit IPO was $6.5B. Arm was $54B. Arm is correct. --@agent:claude-code[model: opus, as: @chris]}
{>> Good point, keeping it. --@bob !!}

```canvas
{
  "nodes": [
    {
      "id": "a",
      "type": "text",
      "x": 0, "y": 0, "width": 250, "height": 120,
      "text": "## Project Overview\nThis is the main objective."
    },
    {
      "id": "b",
      "type": "file",
      "x": 300, "y": 0, "width": 250, "height": 150,
      "file": "./Report/q2-analysis.md"
    },
    {
      "id": "c",
      "type": "link",
      "x": 0, "y": 180, "width": 250, "height": 100,
      "url": "https://github.com/cardstack/boxel"
    },
    {
      "id": "g1",
      "type": "group",
      "x": -20, "y": -20, "width": 580, "height": 320,
      "label": "Research"
    }
  ],
  "edges": [
    {
      "id": "e1",
      "fromNode": "a",
      "toNode": "b",
      "fromSide": "right",
      "toSide": "left",
      "label": "informs"
    }
  ]
}
```

```canvas
{
  "nodes": [
    {
      "id": "0",
      "type": "card",
      "card": "./InvoiceCard/inv-2026-002",
      "x": 120, "y": 120, "width": 280, "height": 364,
      "format": "fitted",
      "zOrder": 0
    },
    {
      "id": "1",
      "type": "card",
      "card": "./HotelRoomCard/garden-villa",
      "x": 432, "y": 120, "width": 280, "height": 364,
      "format": "fitted",
      "zOrder": 1
    },
    {
      "id": "dup-1",
      "type": "card",
      "card": "./HotelRoomCard/garden-villa",
      "x": 757, "y": 1040, "width": 599, "height": 717,
      "format": "isolated",
      "isolatedMode": "natural",
      "isolatedZoom": 1,
      "zOrder": 6
    }
  ]
}
```

```canvas
{
  "nodes": [
    {
      "id": "tile",
      "type": "card",
      "card": "./Theme/athletic-energy",
      "x": 120, "y": 120, "width": 280, "height": 364,
      "format": "fitted",
      "zOrder": 0
    },
    {
      "id": "detail",
      "type": "card",
      "card": "./Theme/athletic-energy",
      "x": 432, "y": 120, "width": 350, "height": 364,
      "format": "embedded",
      "zOrder": 1
    },
    {
      "id": "full",
      "type": "card",
      "card": "./Theme/athletic-energy",
      "x": 814, "y": 120, "width": 450, "height": 500,
      "format": "isolated",
      "isolatedMode": "windowed",
      "isolatedZoom": 0.5,
      "zOrder": 2
    }
  ]
}
```

```canvas
{
  "nodes": [
    {
      "id": "local",
      "type": "card",
      "card": "./InvoiceCard/inv-2026-002",
      "x": 0, "y": 0, "width": 280, "height": 364,
      "format": "fitted"
    },
    {
      "id": "remote",
      "type": "card",
      "card": "https://app.boxel.ai/chris/hover-craft/NbaTradingCard/4d8b37ea",
      "x": 312, "y": 0, "width": 280, "height": 364,
      "format": "fitted"
    },
    {
      "id": "note",
      "type": "text",
      "x": 0, "y": 400, "width": 560, "height": 100,
      "text": "Comparing invoice layout with trading card layout"
    }
  ],
  "edges": [
    { "id": "e1", "fromNode": "local", "toNode": "note" },
    { "id": "e2", "fromNode": "remote", "toNode": "note" }
  ]
}
```

![[my-drawing.excalidraw]]

```excalidraw
{
  "type": "excalidraw",
  "elements": [
    { "type": "rectangle", "x": 10, "y": 10, "width": 200, "height": 100 },
    { "type": "text", "x": 50, "y": 40, "text": "Hello" }
  ]
}
```

```kanban
## Backlog
- Design review
- API documentation
- [ ] Write migration guide

## In Progress
- Parser implementation
- [x] Field registry

## Done
- Spec draft
- Syntax guide
```

```tasks
not done
due before next week
priority is high
path includes Projects
```

```slides
# Welcome
Introduction to the project

---
# Key Findings
<!-- .slide: data-background="#1a1a2e" -->

::card[./Cards/revenue-chart]

---
# Next Steps
- [ ] Ship v1
- [ ] Gather feedback
```

```backlinks
```

```backlinks
format: strip
depth: 1
```

```outlinks
```

```graph
depth: 2
```

```tags
```

```tags
scope: realm
```

```timeline
- 2026-01: Project kickoff
- 2026-03: Alpha release
  Parser and serializer complete
- 2026-04: Beta release
  Display renderer, field hydration
- 2026-06: Public launch
```

```gallery
- ./assets/screenshot-1.png
- ./assets/screenshot-2.png
- ./assets/screenshot-3.png
- ./assets/screenshot-4.png
cols: 2
```

```chart
type: bar
title: Revenue by Quarter
data:
  labels: [Q1, Q2, Q3, Q4]
  datasets:
    - label: 2025
      values: [12, 19, 8, 15]
    - label: 2026
      values: [18, 24, 22, 28]
```

```embed
url: https://github.com/cardstack/boxel
```

```canvas
nodes:
  - id: a
    card: ./Cards/aero-stock
    x: 0
    y: 0
  - id: b
    card: ./Cards/nvda-stock
    x: 300
    y: 0
  - id: c
    text: "These two are correlated"
    x: 150
    y: 150
edges:
  - from: a
    to: c
  - from: b
    to: c
```

```csv
Name, Department, Salary
Alice, Engineering, 145000
Bob, Design, 125000
```

```toc
```

```toc
depth: 2
style: numbered
```

```comments
```

```comments
filter: open
```

```tasks
```

---
renderers:
  toc:
    type: FancyTocField
    from: ./fancy-toc
  comments:
    type: ReviewPanelField
    from: ./review-panel
---

%%%card stock-nvda
type: StockTickerCard
from: ./stock-ticker-card
symbol: NVDA
price: 892.50
change: 2.4
%%%

::card[#stock-nvda]

Report/
  q2-analysis.json              <-- your document
  q2-analysis/                  <-- auto-created subdirectory
    StockTickerCard/            <-- type subdirectory
      stock-nvda.json           <-- real card instance

## Team

%%%card alice
type: TeamMember
from: ./team-member
name: Alice Chen
role: Lead Engineer
status: active
%%%

%%%card bob
type: TeamMember
from: ./team-member
name: Bob Park
role: Design Lead
status: active
%%%

## Milestones

%%%card parser-done
type: Milestone
from: ./milestone
name: BFM Parser
completion: 100
status: completed
dueDate: 2026-03-15
%%%

%%%card renderer-wip
type: Milestone
from: ./milestone
name: Display Renderer
completion: 60
status: in-progress
dueDate: 2026-04-15
%%%

The team: :card[#alice] and :card[#bob]

:::grid[cols:2]
::card[#parser-done]
::card[#renderer-wip]
:::

Report/
  sprint-12.json
  sprint-12/
    TeamMember/
      alice.json
      bob.json
    Milestone/
      parser-done.json
      renderer-wip.json

%%%card aero
type: StockTickerCard
from: ./stock-ticker-card
symbol: AERO
price: 342.10
change: 5.1
%%%

%%%card nvda
type: StockTickerCard
from: ./stock-ticker-card
symbol: NVDA
price: 892.50
change: 2.4
%%%

%%%card tsla
type: StockTickerCard
from: ./stock-ticker-card
symbol: TSLA
price: 178.20
change: -1.8
%%%

:::grid[cols:3]
::card[#aero]
::card[#nvda]
::card[#tsla]
:::