Markdoc widget reference#

Every markdown cell renders through Markdoc. When a query cell runs, its outputName becomes a live variable ($orders, $monthly, etc.) that markdown cells can read. Shared reports use the same pipeline.

For the notebook workflow (preview, toolbar, chart inheritance), see Results, charts, and dashboards. This page is the syntax reference.

Variables from query cells#

Only query cells with results publish variables. Markdown cells, Python cells, and cells that haven't run yet do not.

Given a query cell whose output name is orders:

Column names from the first row are also available as $orders.column_name fields.

If you reference a cell that doesn't exist or hasn't been run, the editor shows a diagnostic and preview renders an error banner. Run upstream cells first.

Live numbers in prose#

Wrap values in {% ... %} so Markdoc evaluates them:

We processed {% $orders.count %} orders.
Revenue hit {% currency($orders.revenue) %} last month.
Peak month: {% formatDate($top.month, "MMM YYYY") %}.

$orders.revenue on its own in plain text is not evaluated. It is only live inside {% %} tags (prose) or tag attributes (value=$orders.revenue on a widget). The toolbar ref picker inserts $cell.column for attribute positions; wrap it yourself when writing sentences.

Format functions (currency, compact, percent, sign, formatDate) work inside those tags. Comparison functions (gt, gte, lt, lte) work inside {% if %} blocks.

Markdoc in Lunapad has no arithmetic operators and no | round pipe. If you need a ratio, percent of total, or rounded share, compute it in a query cell and reference the column:

# share
from totals
derive { pct_of_total = this_value * 100.0 / grand_total }

Then in markdown: {% percent($share.pct_of_total, 1) %}. The percent() function expects a 0–100 scale; it formats decimals and appends %, it does not multiply by 100.

Conditionals#

{% if gt($orders.count, 0) %}
  Has data.
{% else /%}
  No data yet.
{% /if %}

{% else %} must always be self-closing ({% else /%}). Chain extra branches as {% else gt($x, 0) /%}.

Editor shortcuts#

Widget tags#

Widgets use {% tagName ... /%} for self-closing tags or {% tagName %}...{% /tagName %} for blocks. Inside tag attributes, pass data with $cell.field or $cell.rows.

Format functions#

Callable inside {% ... %} prose tags and as attribute values on widgets.

formatDate pattern tokens: YYYY, MMM (3-letter month), MM (zero-padded month), DD (zero-padded day), D (day, no padding).

metric: a single KPI#

{% metric value=$orders.revenue label="Revenue" vs=$previous.revenue format="currency" /%}

chart: any of the chart types#

{% chart type="bar" data=$orders.rows x="month" y="revenue" /%}

datatable: a result table#

{% datatable data=$orders.rows cols=["id","customer","total"] limit=20 /%}

badge: an inline status label#

{% badge value="active" color="success" /%}

progress: a progress bar#

{% progress value=$job.completed max=100 label="Backfill" color="success" /%}

filter: a control that parameterizes upstream queries#

{% filter kind="dropdown" param="region" label="Region" options=$regions.rows optionsColumn="name" /%}

A filter doesn't wrap or filter other widgets directly. Instead, give an upstream query cell a ${param} placeholder:

from orders
filter region == "${region}"

Changing the filter control re-runs that query cell (and anything downstream of it) with the new value substituted in as raw text, so wrap it in quotes yourself for a string literal. Embedded single quotes in the value are escaped automatically.

details: a collapsible section#

{% details summary="Methodology" open=false %}
Anything can go in here: paragraphs, other widgets, lists.
{% /details %}

tabs / tab: a tabbed group#

{% tabs %}
  {% tab label="Summary" %}
    {% metric value=$total.revenue format="currency" /%}
  {% /tab %}
  {% tab label="By region" %}
    {% chart type="bar" data=$byRegion.rows x="region" y="revenue" /%}
  {% /tab %}
{% /tabs %}

tabs only accepts tab children. Each tab requires a label and can contain anything.

columns / column: side-by-side layout#

{% columns %}
  {% column width="300px" %}
    {% metric value=$daily.revenue label="Today" format="currency" /%}
  {% /column %}
  {% column %}
    {% chart type="line" data=$trend.rows x="day" y="revenue" /%}
  {% /column %}
{% /columns %}

column takes an optional width (pixels, a percentage string, or an fr unit). Columns with no width split the row evenly.

grid: a multi-column grid#

{% grid cols=2 %}
  {% card title="Q1" %}{% metric value=$q1.revenue format="currency" /%}{% /card %}
  {% card title="Q2" %}{% metric value=$q2.revenue format="currency" /%}{% /card %}
{% /grid %}

cols (number, default 3) sets the column count. Children flow left to right, wrapping into new rows.

callout: a colored note box#

{% callout type="warning" %}
This can't be undone.
{% /callout %}

type (default info): info, success, warning, error.

card: a bordered section#

{% card title="Monthly summary" %}
  {% metric value=$monthly.revenue label="Revenue" format="currency" /%}
{% /card %}

title is optional; omit it for an untitled card.

mermaid: diagrams (all Mermaid types)#

Use {% mermaid %}...{% /mermaid %} for any Mermaid diagram type: flowchart, sequenceDiagram, stateDiagram-v2, erDiagram, gantt, pie, gitGraph, classDiagram, kanban, mindmap, timeline, and others.

Fenced ```mermaid blocks also render. They are the most reliable option for static diagrams. Only {% mermaid %} supports data-driven generation with {% group %} and {% each %} loop tags.

Static: source is preserved literally (newlines, YAML --- frontmatter, [*] state nodes, etc.):

{% mermaid %}
---
title: Order flow
---
stateDiagram-v2
    [*] --> Still
    Still --> [*]
{% /mermaid %}

Dynamic: embed {% group %} and {% each %} inside the mermaid body. The expander slices your template from the original source and interpolates bare $column tokens, preserving whitespace and indentation exactly as written. That matters for mindmap, flowchart subgraphs, and sequence diagrams. Use $keyId for Mermaid ids when the grouped value contains spaces ($keyId is slugified; $key is the display value).

Loop tag rules: do not put blank lines inside a {% each %} body (Markdoc treats them as block boundaries and breaks tag nesting). Put {% /each %} on the line immediately after the template row.

{% mermaid %}
kanban
  {% group data=$tasks.rows by="status" order=["Todo","In Progress","Review","Done"] %}
  $keyId[$key]
    {% each data=$items %}
    t$id[$title]@{ ticket: $ticket, priority: '$priority', assigned: '$assignee' }
    {% /each %}
  {% /group %}
{% /mermaid %}

Optional attribute: code=$cell.field to pass pre-built diagram text from a cell variable instead of a body.

group / each: loop tags for diagram templates#

Primarily used inside {% mermaid %}, but usable elsewhere.

{% group data=$rows by="column" order=[...] %} groups rows and exposes $key, $keyId, and $items in the body per group.

{% each data=$rows %} or {% each data=$items %} iterates rows and exposes all columns as $col in the body.

Common mistakes#

Full dashboard example#

Query cells (run these first):

# orders — seed table
from orders

# monthly_revenue
from orders
derive { month = date_trunc("month", order_date) }
group month ( aggregate { total_revenue = sum amount } )

# region_performance
from orders
group region ( aggregate { total_revenue = sum amount, order_count = count this } )

Markdown cell:

## Revenue dashboard

{% badge value="Live" color="success" /%}

Month to date: **{% currency($monthly_revenue.total_revenue) %}** across {% $orders.count %} orders.

{% grid cols=2 %}
{% metric value=$monthly_revenue.total_revenue label="Revenue" format="currency" /%}
{% metric value=$region_performance.order_count label="Orders" /%}
{% /grid %}

{% chart type="bar" data=$region_performance.rows x="region" y="total_revenue" title="By region" /%}

Publish via Share or add the notebook to a Site.

Next#

AI assistant.