Data

Feed charts and sortable tables from real data files instead of hand-typed Markdown tables. The data rune reads an external tabular source at build time, shapes it (filter, sort, select, type), and emits a plain <table> — which {% chart %} and {% datatable %} consume with no extra work, and which stands on its own as the no-JS fallback.

Ingest a file

The minimum case — a src attribute relative to the project root. The format is inferred from the extension.

{% data src="site/examples/revenue.csv" /%}

<div class="rf-table-wrapper">
  <table>
    <thead>
      <tr>
        <th>product</th>
        <th>revenue</th>
        <th>region</th>
        <th>units</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Widget</td>
        <td data-value="1200">$1,200</td>
        <td>EMEA</td>
        <td data-value="340">340</td>
      </tr>
      <tr>
        <td>Gadget</td>
        <td data-value="900">$900</td>
        <td>AMER</td>
        <td data-value="210">210</td>
      </tr>
      <tr>
        <td>Gizmo</td>
        <td data-value="1500">$1,500</td>
        <td>EMEA</td>
        <td data-value="120">120</td>
      </tr>
      <tr>
        <td>Sprocket</td>
        <td data-value="1050">$1,050</td>
        <td>APAC</td>
        <td data-value="260">260</td>
      </tr>
    </tbody>
  </table>
</div>

<div class="rf-table-wrapper">
  <table>
    <thead>
      <tr>
        <th>product</th>
        <th>revenue</th>
        <th>region</th>
        <th>units</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Widget</td>
        <td data-value="1200">$1,200</td>
        <td>EMEA</td>
        <td data-value="340">340</td>
      </tr>
      <tr>
        <td>Gadget</td>
        <td data-value="900">$900</td>
        <td>AMER</td>
        <td data-value="210">210</td>
      </tr>
      <tr>
        <td>Gizmo</td>
        <td data-value="1500">$1,500</td>
        <td>EMEA</td>
        <td data-value="120">120</td>
      </tr>
      <tr>
        <td>Sprocket</td>
        <td data-value="1050">$1,050</td>
        <td>APAC</td>
        <td data-value="260">260</td>
      </tr>
    </tbody>
  </table>
</div>

That is a real file in this repository, read at build time. Change the file and the table updates on the next build — no copy-paste drift. Note the emitted table is a normal table: it renders with or without JavaScript.

Feeding a chart

Because chart treats an authored <table> as its single source of truth, dropping a {% data %} inside it is all it takes. numeric types the value column so the chart plots real numbers (see Typing).

{% chart type="bar" title="Revenue by product" %}
{% data src="site/examples/revenue.csv" columns="product, revenue" numeric="revenue" /%}
{% /chart %}

<rf-chart data-rune="chart" data-rune-fields="{&quot;type&quot;:&quot;bar&quot;,&quot;stacked&quot;:&quot;false&quot;}">
  <table data-name="data">
    <caption>Revenue by product</caption>
    <thead>
      <tr>
        <th>product</th>
        <th>revenue</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Widget</td>
        <td data-value="1200">$1,200</td>
      </tr>
      <tr>
        <td>Gadget</td>
        <td data-value="900">$900</td>
      </tr>
      <tr>
        <td>Gizmo</td>
        <td data-value="1500">$1,500</td>
      </tr>
      <tr>
        <td>Sprocket</td>
        <td data-value="1050">$1,050</td>
      </tr>
    </tbody>
  </table>
</rf-chart>

<rf-chart class="rf-chart" data-type="bar" data-stacked="false" data-elevation="sunken" data-rune="chart" data-density="compact">
  <table data-name="data" class="rf-chart__data">
    <caption>Revenue by product</caption>
    <thead>
      <tr>
        <th>product</th>
        <th>revenue</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Widget</td>
        <td data-value="1200">$1,200</td>
      </tr>
      <tr>
        <td>Gadget</td>
        <td data-value="900">$900</td>
      </tr>
      <tr>
        <td>Gizmo</td>
        <td data-value="1500">$1,500</td>
      </tr>
      <tr>
        <td>Sprocket</td>
        <td data-value="1050">$1,050</td>
      </tr>
    </tbody>
  </table>
</rf-chart>

Feeding a datatable

Same table, handed to datatable for runtime search + sort. Typed-numeric columns sort by their real value, not the formatted text ($1,200 sorts above $900, not below it):

{% datatable sortable="all" searchable=true %}
{% data src="site/examples/revenue.csv" numeric="revenue,units" /%}
{% /datatable %}

<div data-rune="data-table" data-rune-fields="{&quot;sortable&quot;:&quot;all&quot;,&quot;searchable&quot;:&quot;true&quot;,&quot;pageSize&quot;:&quot;0&quot;,&quot;defaultSort&quot;:&quot;&quot;}">
  <div data-name="scroll">
    <table data-name="table">
      <thead>
        <tr>
          <th>product</th>
          <th>revenue</th>
          <th>region</th>
          <th>units</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>Widget</td>
          <td data-value="1200">$1,200</td>
          <td>EMEA</td>
          <td data-value="340">340</td>
        </tr>
        <tr>
          <td>Gadget</td>
          <td data-value="900">$900</td>
          <td>AMER</td>
          <td data-value="210">210</td>
        </tr>
        <tr>
          <td>Gizmo</td>
          <td data-value="1500">$1,500</td>
          <td>EMEA</td>
          <td data-value="120">120</td>
        </tr>
        <tr>
          <td>Sprocket</td>
          <td data-value="1050">$1,050</td>
          <td>APAC</td>
          <td data-value="260">260</td>
        </tr>
      </tbody>
    </table>
  </div>
</div>

<div class="rf-datatable rf-datatable--true rf-datatable--all rf-datatable--0" data-searchable="true" data-sortable="all" data-page-size="0" data-default-sort="" data-elevation="sunken" data-rune="data-table" data-density="compact">
  <div data-name="scroll" class="rf-datatable__scroll">
    <table data-name="table" class="rf-datatable__table" data-section="body">
      <thead>
        <tr>
          <th>product</th>
          <th>revenue</th>
          <th>region</th>
          <th>units</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>Widget</td>
          <td data-value="1200">$1,200</td>
          <td>EMEA</td>
          <td data-value="340">340</td>
        </tr>
        <tr>
          <td>Gadget</td>
          <td data-value="900">$900</td>
          <td>AMER</td>
          <td data-value="210">210</td>
        </tr>
        <tr>
          <td>Gizmo</td>
          <td data-value="1500">$1,500</td>
          <td>EMEA</td>
          <td data-value="120">120</td>
        </tr>
        <tr>
          <td>Sprocket</td>
          <td data-value="1050">$1,050</td>
          <td>APAC</td>
          <td data-value="260">260</td>
        </tr>
      </tbody>
    </table>
  </div>
</div>

Shaping the data

Every knob below runs at build time on a single intermediate shape, identically regardless of source format. Order: where → sort → columns → limit/offset, then typing.

{% data src="site/examples/revenue.csv"
   where="region:EMEA"
   sort="-units"
   columns="product as Product, units as Units"
   numeric="units" /%}

<div class="rf-table-wrapper">
  <table>
    <thead>
      <tr>
        <th>Product</th>
        <th>Units</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Widget</td>
        <td data-value="340">340</td>
      </tr>
      <tr>
        <td>Gizmo</td>
        <td data-value="120">120</td>
      </tr>
    </tbody>
  </table>
</div>

<div class="rf-table-wrapper">
  <table>
    <thead>
      <tr>
        <th>Product</th>
        <th>Units</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Widget</td>
        <td data-value="340">340</td>
      </tr>
      <tr>
        <td>Gizmo</td>
        <td data-value="120">120</td>
      </tr>
    </tbody>
  </table>
</div>

• where filters rows with the field:value grammar (the same one collection and aggregate use — exact, glob*, or /regex/). Repeat a field to OR; combine fields to AND.
• sort orders by a column; a - prefix descends. A column whose cells are all numeric (even when formatted, like $1,200) sorts numerically.
• columns selects, reorders, and renames: "revenue as 'Revenue ($)'". Quote an alias that contains spaces or punctuation.
• limit / offset slice the rows — the data analogue of snippet's lines=.

Per-row templates — give data a body

Without a body, data emits a <table>. Give it one and the body is rendered once per row, with $row bound to that row — so a data file can drive arbitrary Markdoc, not just table cells.

{% data src="team.csv" sort="name" %}
{% card %}
### {% $row.name %}

{% $row.role %}
{% /card %}
{% /data %}

$row.<column> reads a cell by its column name — after columns renaming, so columns="full_name as name" gives you $row.name. A column that types as numeric binds as a number; everything else binds as the cell's text.

Every shaping attribute applies exactly as it does to the table form: where, sort, columns, limit and offset all run first, and the body sees what survives.

It composes with runes that read their own children

The rendered rows are spliced in as siblings, landing exactly where hand-written ones would. So a parent rune that builds structure from its children — accordion, tabs, bento — works with generated items:

{% accordion %}
{% data src="faq.csv" %}
{% accordion-item %}
## {% $row.question %}

{% $row.answer %}
{% /accordion-item %}
{% /data %}
{% /accordion %}

A variable inside backticks is literal

Markdoc does not interpolate inside inline code, so this renders the text {% $row.name %} rather than the value:

### `{% $row.name %}`

Nothing warns — you get a heading per row, each showing the same literal.

This is standard Markdown, and it is the only inline construct with the property: links, nested emphasis and rune bodies all pass a variable through fine. Use {% code %} when you want the value code-styled:

### {% code %}{% $row.name %}{% /code %}

A table with formatted cells

Set headers and the body becomes one table row — cells separated by --- — instead of a run of blocks:

{% data src="_data/rune-attributes.json" root="attributes" where="rune:card scope:own"
        headers="Attribute, Type, Required, Description" %}
{% code %}{% $row.name %}{% /code %}
---
{% $row.type %}
---
{% if $row.required %}✓{% else /%}—{% /if %}
---
{% $row.description %}
{% /data %}

This is how you get a table whose cells carry markup. The bodyless form above builds its cells from literal text — right for arbitrary CSV, where a stray * should stay a * — so it can render true but never ✓, and href but never `href`. Here the cells are markdown you wrote, so emphasis, links, runes and {% if %} all work inside one.

The emitted table is structurally identical to the bodyless one, so chart and datatable consume it unchanged.

Three things to know:

• The counts must match. headers naming four columns and a body with three ----delimited cells is a build error that names both numbers.
• headers needs a body. On a self-closing tag it is an error rather than a silent no-op — it would read as a rename of columns, which selects and renames source columns instead.
• A --- inside a cell splits it. The same constraint card and grid carry. Watch for it in free-text columns.

Nested queries

A {% data %} inside another one's body runs as a subquery, once per outer row:

{% data src="axes.json" where=$r %}
## {% $row.axis %}

{% data src="axis-attributes.json" where=$row.query headers="Attribute, Type" %}
{% code %}{% $row.name %}{% /code %}
---
{% $row.type %}
{% /data %}
{% /data %}

$row always means the nearest enclosing query's row — so the inner table sees attribute rows even though both sources have a name column. The one place the outer row reaches in is the subquery's attributes: where=$row.query is how the subquery gets filtered for this row, which is the whole point.

Because where takes a single string and nothing here concatenates, the filter value has to arrive ready-made. Emit it as a column (query above holds "axis:bg") rather than trying to build it at the call site.

An empty subquery renders nothing and does not take its row with it — a row whose subquery finds no matches still renders its own content.

Limits

The binding is deliberately shallow — bind a row, render a block. {% if %} works ({% else /%} is self-closing), but there is no iteration, and formatting goes through the shared Markdoc functions, the same constraint collection templates hold.

Two more:

• $item is not an alias for $row. A collection's $item is an entity (id / type / url / data); a data row is flat. One name for two shapes is a trap, so reaching for $item.data.x here is an error rather than a silent undefined.
• Not inside chart or datatable. Those consume the <table> this rune would otherwise emit, so a body there is a build error rather than an empty render.
• numeric / text warn. They exist to type the data-value attribute on table cells; a body emits no cells. Numeric columns still bind to $row as numbers.

Typing and the data-value channel

A Markdown table carries only text, so a formatted number ($1,200, 1,500, 98%) is just a string. numeric types a column: every value cell keeps its human-formatted text and gains a normalized data-value ("$1,200" → data-value="1200").

That one attribute is the typed channel both host runes honour:

• chart reads data-value for the plotted number (falling back to the cell text).
• datatable's sort prefers data-value, so currency and thousands-separated columns sort correctly.

Auto-inference handles the common case — a column whose non-empty cells all parse as numbers becomes numeric automatically. Use numeric="col" to force it (e.g. a column with a few blanks or footnote markers) and text="col" to keep something like a zero-padded code (007) as text. data-value is invisible to a reader of the bare table — a pure enhancement.

JSON and NDJSON

JSON isn't inherently tabular, so its adapter owns three extra knobs; everything downstream is identical to CSV.

Nested JSON, plucked with a root locator and dotted column paths:

{% data src="data/api-dump.json" root="data.results" where="region:EMEA"
   columns="product as Product, geo.country as Country, units as Units"
   numeric="units" sort="-units" /%}

• root — a dotted path (data.results) or JSON Pointer (/data/results) to the array or map inside the document. Defaults to the document itself when it is already an array.
• orient — how each element maps to a row:
  • records (default, auto-detected) — [{name, revenue}, …], keys become headers.
  • values (auto-detected) — [["name","revenue"],["a",10]], the first inner array is the header row.
  • index (explicit) — { "us": {…}, … }, an object map; the key becomes a column named by key-column.
• dotted column paths — nested fields flatten to dotted headers (geo.country), so columns plucks them by name.

Object-map JSON into a datatable:

{% datatable sortable="all" searchable=true %}
{% data src="data/inventory.json" orient="index" key-column="sku"
   columns="sku as SKU, name as Item, stock as Stock" numeric="stock" /%}
{% /datatable %}

NDJSON (newline-delimited JSON) parses one record per line; the union of record keys becomes the headers:

{% data src="data/events.ndjson" columns="ts as Time, type as Event" /%}

Build time vs. runtime — data and datatable

data's where/sort/columns overlap conceptually with what datatable offers, but they run at a different time, and they compose:

Use data to scope and type what lands on the page (the honest fallback); wrap it in datatable to let readers explore that set. Reach for data's knobs to remove rows from the output, and datatable's to let readers hide rows they still could reveal.

Format inference

format is inferred from the file extension and can always be overridden.

When something goes wrong

A sandbox escape, a missing file, a parse error, or a source that yielded no rows renders a visible error callout in place of the table and records a build error — the build keeps going, and the failure is obvious on the page rather than silently producing a broken table. "No rows" here means the file or the root you pointed at held nothing; it is a wrong-target mistake.

A filter that legitimately matched nothing is not an error. {% data %} renders nothing at all and says nothing — asking real data a question with no answer today is normal, and a page listing open bugs when there are none is working, not broken.

An attribute the rune cannot read is a build error naming what went wrong. data resolves its attributes during the preprocess phase, so a few things that look like they should work cannot:

data: `where` is a call to `concat()`, and `data` reads its attributes
      during preprocess — before functions are evaluated
data: `where` references `$missing`, which is not defined here
data: `where` is empty

This matters more than it sounds. An unreadable where used to resolve to an empty string, and an empty filter is no filter — so the page rendered the whole source instead of erroring. On a page filtering one rune's attributes out of a catalogue, that renders every rune's attributes under that rune's heading and looks completely plausible.

Omitting an attribute is untouched: only attributes you actually wrote are checked.

That leaves the mistake worth catching on its own: a misspelt column. Any where, sort, or columns clause naming a column the source does not have emits a build warning that names the column and lists the ones that exist:

data "revenue.csv": `where` names a column the source does not have: "regio". Available: region, quarter, revenue.

The warning fires whether or not the result ends up empty — a clause that matches nothing is a mistake even when another clause still returns rows.

SQLite — a later tier

A SQLite adapter is specified but not yet implemented. It will slot into the same { headers, rows } contract, but it is active rather than passive — its path to a result set is a query (table="sales" or query="SELECT …" with params for safe binding), and rows arrive pre-typed. Because a query engine can reach outside the file, the adapter will open the database read-only, disable extension loading, and reject ATTACH / file-touching pragmas on top of the path sandbox — build-time only, never exposed to the client. Tracked as its own work item.

Attributes

Every attribute in one table. Format-specific ones say so in their description — CSV/TSV: or JSON:; the rest apply to every source.

Universal attributes

See also

• Chart — plots the emitted table; reads data-value for real numbers.
• Datatable — runtime search/sort over the emitted table; sorts on data-value.
• Snippet — the sibling preprocess rune (a file → a code fence).
• Hosted & in-memory builds — the ProjectFiles sandbox data's src reads through.