Metrics

Metrics render a table as tiles: label, value, and an optional delta whose leading + or - sets a direction. direction=inverse flips which sign reads as positive, for metrics like churn where down is good. The content must be exactly one table with at least two columns.

The header row names the columns for readers of the raw table; the tiles do not show it.

Attributes

Content must be exactly one table with at least two columns. Column roles are positional: label, value, and an optional delta. A delta beginning with + or - takes a direction from its sign, and direction=inverse flips which sign reads as good, for a measure like churn.

Downgrade: the table, unchanged.

Watch for: the header row is not rendered as a tile, but write it anyway. It is what makes the raw table readable to anyone who sees the source rather than the render.

Examples

A table of at least two columns. The first is the label, the second the value, and an optional third is read as a delta.

:::metrics
| Metric  | Value | Δ     |
|---------|-------|-------|
| Revenue | $4.2M | +12%  |
| Churn   | 2.1%  | -0.4% |
:::

| Metric  | Value | Δ     |
| ------- | ----- | ----- |
| Revenue | $4.2M | +12%  |
| Churn   | 2.1%  | -0.4% |

direction=inverse flips which sign reads as good, for a measure like churn where down is the improvement.

:::metrics{direction=inverse}
| a | b |
|---|---|
| 1 | 2 |
:::

| a | b |
| - | - |
| 1 | 2 |

The delta column is optional. Without it the tiles are label and value only.

:::metrics
| a | b |
|---|---|
| 1 | 2 |
:::

| a | b |
| - | - |
| 1 | 2 |

GFM column alignment survives into the tiles, so numeric columns stay aligned.

:::metrics
| a | b |
|:--|--:|
| 1 | 2 |
:::

| a  |  b |
| :- | -: |
| 1  |  2 |

What the validator catches

Every error below is specified; nothing degrades silently.

:::metrics
:::

:::metrics
- a
:::

:::metrics
| a |
|---|
| 1 |
:::

All 12 cases for metrics are in the conformance browser. The normative text is spec §4.