- Version 2.0 Adds provision to dynamic values - Section 13 - Dynamic Values
This specification defines a simple syntax for representing charts in Markdown documents using fenced blocks with the chart language identifier.
The goal is to enable charts that are easy to write by hand, readable as plain text, and renderable by an external engine — for example, one based on Chart.js, ECharts, Vega, SVG, or another implementation.
This initial version supports only the following types:
-
bar -
line -
area -
scatter -
bubble -
pie
Every chart must be declared inside a fenced block:
type: bar
title: Sales by product
data: [cols=Product,Revenue, rows=("Product A",120),("Product B",80),("Product C",160)]
label: Product
value: Revenue
The inner content uses key: value pairs.
| Field | Required | Description |
|---|---|---|
type |
Yes | Primary chart type |
variant |
No | Structural or visual variation of the chart |
orientation |
No | Chart orientation, when applicable |
title |
No | Main chart title |
source |
Conditional | Reference to a Markdown table |
range |
No | Optional slice of the referenced table |
data |
Conditional | Inline data |
label |
Conditional | Field used as label |
value |
Conditional | Field used as value |
x |
Conditional | Field used on the X axis |
y |
Conditional | Field used on the Y axis |
series |
Conditional | Fields used as multiple series |
size-value |
Conditional | Field used as bubble size in bubble charts |
data-color |
No | Data colors |
bg-color |
No | Chart background color |
border |
No | Chart or element border |
position |
No | Suggested chart position |
size |
No | Suggested chart size |
subtitles |
No | Legend/subtitle position and colors |
A chart must use exactly one of the two data sources:
data:
or:
source:
Using data and source simultaneously must be considered invalid.
Bar chart.
Allowed variants:
default
stacked
grouped
floating
Allowed orientations:
vertical
horizontal
Example:
type: bar
variant: stacked
orientation: vertical
Line chart.
Allowed variants:
default
smooth
stepped
Example:
type: line
variant: smooth
Area chart.
Allowed variants:
default
stacked
normalized
Example:
type: area
variant: stacked
Scatter chart.
Allowed variants:
default
Example:
type: scatter
Bubble chart.
Allowed variants:
default
Example:
type: bubble
The type field defines the primary chart family.
Example:
type: bar
Valid types in this version:
bar
line
area
scatter
bubble
The variant field defines a structural or visual variation of the chart.
Example:
type: bar
variant: floating
When variant is omitted, the assumed value must be:
default
Variant table:
type |
Allowed variant values |
|---|---|
bar |
default, stacked, grouped, floating |
line |
default, smooth, stepped |
area |
default, stacked, normalized |
scatter |
default |
bubble |
default |
The orientation field defines the chart orientation when applicable.
Allowed values:
vertical
horizontal
When orientation is omitted, the assumed value must be:
vertical
In this version, orientation applies primarily to bar charts.
Example:
type: bar
orientation: horizontal
Inline data must use a single valid syntax:
data: [cols=<column1>,<column2>,..., rows=(<value1>,<value2>,...),(<value1>,<value2>,...)]
Example:
type: bar
title: Sales by product
data: [cols=Product,Revenue, rows=("Product A",120),("Product B",80),("Product C",160)]
label: Product
value: Revenue
This example represents the logical table:
| Product | Revenue |
|---|---|
| Product A | 120 |
| Product B | 80 |
| Product C | 160 |
dataalways uses the[cols=..., rows=...]format.colsmust come beforerows.colsis a comma-separated list of column names.rowsis a list of parenthesized rows.- Each row must have exactly the same number of values as
cols. - Spaces outside quotes are ignored.
- Values containing relevant spaces, commas, parentheses, brackets, or
=must be quoted. - Strings may use double or single quotes.
- Numbers must be inferred automatically by the renderer.
- There is no alternative shorthand form for
data.
When a value contains relevant spaces, commas, or special characters, it must be enclosed in quotes.
Example:
type: bar
title: Revenue by product
data: [cols=Product,Revenue, rows=("Product A",120),("Product B",80),("Product C",160)]
label: Product
value: Revenue
Single quotes are also allowed:
type: bar
title: Revenue by product
data: [cols=Product,Revenue, rows=('Product A',120),('Product B',80),('Product C',160)]
label: Product
value: Revenue
A Markdown table can be used as a data source.
The table must receive an identifier using the syntax:
{: #table-id }Example:
| Product | Revenue |
|-----------|--------:|
| Product A | 120 |
| Product B | 80 |
| Product C | 160 |
{: #product-sales }The chart references the table using source:
type: bar
title: Sales by product
source: #product-sales
label: Product
value: Revenue
The range field allows using only a portion of the referenced table.
The canonical form is:
range: [rows=1..10, cols=Product,Revenue]
range may only be used together with source.
Select rows 1 through 10:
range: [rows=1..10]
Select from row 2 to the end:
range: [rows=2..]
Select from the beginning through row 5:
range: [rows=..5]
Select specific rows:
range: [rows=1,3,5]
Select columns by name:
range: [cols=Product,Revenue]
Select columns by letter:
range: [cols=A,B]
Select a column range:
range: [cols=A:C]
Select rows and columns:
range: [rows=1..10, cols=Product,Revenue]
Row counting starts at the first data row.
The table header does not count as a data row.
Example:
| Product | Revenue |
|-----------|--------:|
| Product A | 120 |
| Product B | 80 |
| Product C | 160 |
{: #sales }Mapping:
| Reference | Value |
|---|---|
A1 |
Product A |
B1 |
120 |
A2 |
Product B |
B2 |
80 |
A3 |
Product C |
B3 |
160 |
rangeis optional.rangemay only be used withsource.- Row counting starts at the first data row.
- The table header does not count as a data row.
- Row indices are inclusive.
- Column letters follow spreadsheet style:
A,B,C, ...,Z,AA,AB. - Spaces outside quotes are ignored.
- When
rangelimits columns, the fields used by the chart must exist within the slice. - If
rangeconflicts withlabel,value,x,y,series, orsize-value, the renderer must emit an error.
Defines the primary data colors.
data-color: #6538fe #786fe6 #7375ef
When omitted, the renderer may choose colors automatically.
Defines the chart background color.
bg-color: #ffffff
When omitted, the default value must be:
#ffffff
Defines whether there is a border and, optionally, the thickness.
Format:
border: <true|false> <thickness>
Examples:
border: true
border: true 2
border: false
When omitted, the default value must be:
false
Defines a suggested position in pixels.
Format:
position: <x>x<y>
Example:
position: 50x60
The renderer may ignore this field.
Defines the suggested chart size in pixels.
Format:
size: <width>x<height>
Example:
size: 700x300
The renderer may adapt this value to the available layout.
Defines the position and, optionally, the colors of the legend/subtitle area.
Format:
subtitles: <position> <background-color> <foreground-color>
Allowed positions:
none
top
bottom
left
right
Examples:
subtitles: top
subtitles: bottom #ffffff #000000
subtitles: none
When colors are omitted, the renderer must choose suitable colors based on bg-color.
For a single bar:
label
value
Example:
type: bar
data: [cols=Product,Revenue, rows=("Product A",120),("Product B",80)]
label: Product
value: Revenue
For a bar with multiple series:
x
series
Example:
type: bar
variant: stacked
data: [cols=Month,Store,Online, rows=(Jan,120,90),(Feb,140,130)]
x: Month
series: Store, Online
For a floating bar:
label
value
The value field must point to two values: start and end.
Example:
type: bar
variant: floating
data: [cols=Phase,Start,End, rows=(Planning,0,4),(Design,3,8)]
label: Phase
value: Start, End
For a single line:
x
y
Example:
type: line
data: [cols=Month,Revenue, rows=(Jan,120),(Feb,180),(Mar,150)]
x: Month
y: Revenue
For a line with multiple series:
x
series
Example:
type: line
data: [cols=Month,Store,Online, rows=(Jan,120,90),(Feb,140,130)]
x: Month
series: Store, Online
For a single area:
x
y
Example:
type: area
data: [cols=Day,Users, rows=(Mon,1200),(Tue,1350),(Wed,1280)]
x: Day
y: Users
For an area with multiple series:
x
series
Example:
type: area
variant: stacked
data: [cols=Month,Basic,Pro,Enterprise, rows=(Jan,300,120,40),(Feb,340,150,50)]
x: Month
series: Basic, Pro, Enterprise
Expected fields:
x
y
Optional field:
label
Example:
type: scatter
data: [cols=Product,Price,Demand, rows=(A,10,120),(B,15,100),(C,20,70)]
x: Price
y: Demand
label: Product
Expected fields:
x
y
size-value
Optional field:
label
Example:
type: bubble
data: [cols=Product,Revenue,Margin,Customers, rows=("Product A",120,30,400),("Product B",80,45,250)]
x: Revenue
y: Margin
size-value: Customers
label: Product
type: bar
title: Sales by product
data: [cols=Product,Revenue, rows=("Product A",120),("Product B",80),("Product C",160),("Product D",60)]
label: Product
value: Revenue
data-color: #6538fe #786fe6 #7375ef #9d8cff
bg-color: #ffffff
border: true 1
size: 600x300
subtitles: bottom
| Product | Revenue |
|-----------|--------:|
| Product A | 120 |
| Product B | 80 |
| Product C | 160 |
| Product D | 60 |
{: #product-revenue }type: bar
orientation: horizontal
title: Revenue by product
source: #product-revenue
label: Product
value: Revenue
data-color: #6538fe
size: 600x300
| Month | Store | Online | Partners |
|-------|------:|-------:|---------:|
| Jan | 120 | 90 | 40 |
| Feb | 140 | 130 | 50 |
| Mar | 160 | 170 | 70 |
| Apr | 150 | 190 | 80 |
{: #channel-sales }type: bar
variant: stacked
title: Sales by channel
source: #channel-sales
x: Month
series: Store, Online, Partners
data-color: #6538fe #786fe6 #7375ef
size: 700x350
subtitles: top
type: bar
variant: grouped
title: Sales by channel
data: [cols=Month,Store,Online,Partners, rows=(Jan,120,90,40),(Feb,140,130,50),(Mar,160,170,70),(Apr,150,190,80)]
x: Month
series: Store, Online, Partners
data-color: #6538fe #786fe6 #7375ef
size: 700x350
subtitles: top
type: bar
variant: floating
title: Duration by phase
data: [cols=Phase,Start,End, rows=(Planning,0,4),(Design,3,8),(Implementation,7,16),(Testing,14,20)]
label: Phase
value: Start, End
data-color: #6538fe
size: 700x300
type: line
title: Monthly revenue
data: [cols=Month,Revenue, rows=(Jan,120),(Feb,180),(Mar,150),(Apr,220)]
x: Month
y: Revenue
data-color: #6538fe
size: 700x300
| Month | Revenue |
|-------|--------:|
| Jan | 120 |
| Feb | 180 |
| Mar | 150 |
| Apr | 220 |
| May | 260 |
| Jun | 240 |
{: #monthly-revenue }type: line
variant: smooth
title: Monthly revenue
source: #monthly-revenue
x: Month
y: Revenue
range: [rows=1..6, cols=Month,Revenue]
data-color: #6538fe
size: 700x300
subtitles: bottom
| Month | Store | Online |
|-------|------:|-------:|
| Jan | 120 | 90 |
| Feb | 140 | 130 |
| Mar | 160 | 170 |
| Apr | 150 | 190 |
{: #line-channels }type: line
title: Sales by channel
source: #line-channels
x: Month
series: Store, Online
data-color: #6538fe #786fe6
size: 700x300
type: line
variant: stepped
title: Inventory throughout the week
data: [cols=Day,Inventory, rows=(Mon,120),(Tue,100),(Wed,130),(Thu,90),(Fri,140)]
x: Day
y: Inventory
data-color: #6538fe
size: 700x300
type: area
title: Active users
data: [cols=Day,Users, rows=(Mon,1200),(Tue,1350),(Wed,1280),(Thu,1600),(Fri,1900)]
x: Day
y: Users
data-color: #6538fe
bg-color: #ffffff
size: 700x300
| Month | Basic | Pro | Enterprise |
|-------|------:|-----:|-----------:|
| Jan | 300 | 120 | 40 |
| Feb | 340 | 150 | 50 |
| Mar | 390 | 180 | 70 |
| Apr | 420 | 210 | 90 |
{: #subscription-plans }type: area
variant: stacked
title: Subscriptions by plan
source: #subscription-plans
x: Month
series: Basic, Pro, Enterprise
data-color: #6538fe #786fe6 #7375ef
size: 700x350
subtitles: top
type: area
variant: normalized
title: Share by channel
data: [cols=Month,Organic,Paid,Social, rows=(Jan,40,35,25),(Feb,45,30,25),(Mar,50,28,22)]
x: Month
series: Organic, Paid, Social
data-color: #6538fe #786fe6 #7375ef
size: 700x350
type: scatter
title: Price vs Demand
data: [cols=Product,Price,Demand, rows=(A,10,120),(B,15,100),(C,20,70),(D,30,40)]
x: Price
y: Demand
label: Product
data-color: #6538fe
size: 600x400
| Product | Price | Demand | Category |
|-----------|------:|-------:|------------|
| Product A | 10 | 120 | Basic |
| Product B | 15 | 100 | Basic |
| Product C | 20 | 70 | Pro |
| Product D | 30 | 40 | Pro |
| Product E | 40 | 30 | Enterprise |
{: #price-demand }type: scatter
title: Price vs Demand
source: #price-demand
range: [rows=1..4, cols=Product,Price,Demand]
x: Price
y: Demand
label: Product
data-color: #6538fe
size: 600x400
type: bubble
title: Market by product
data: [cols=Product,Revenue,Margin,Customers, rows=("Product A",120,30,400),("Product B",80,45,250),("Product C",160,25,600),("Product D",60,50,180)]
x: Revenue
y: Margin
size-value: Customers
label: Product
data-color: #6538fe #786fe6 #7375ef #9d8cff
size: 700x400
| Product | Revenue | Margin | Customers |
|-----------|--------:|-------:|----------:|
| Product A | 120 | 30 | 400 |
| Product B | 80 | 45 | 250 |
| Product C | 160 | 25 | 600 |
| Product D | 60 | 50 | 180 |
| Product E | 200 | 20 | 900 |
{: #market-products }type: bubble
title: Revenue, margin, and customer base
source: #market-products
range: [rows=1..5, cols=Product,Revenue,Margin,Customers]
x: Revenue
y: Margin
size-value: Customers
label: Product
data-color: #6538fe #786fe6 #7375ef #9d8cff #b8a8ff
size: 700x400
subtitles: right
A chart must have exactly one data source:
data
or:
source
Valid:
type: bar
data: [cols=Product,Revenue, rows=("Product A",120),("Product B",80)]
label: Product
value: Revenue
Valid:
type: bar
source: #sales
label: Product
value: Revenue
Invalid:
type: bar
source: #sales
data: [cols=Product,Revenue, rows=("Product A",120),("Product B",80)]
label: Product
value: Revenue
range must only be used together with source.
Valid:
type: line
source: #revenue
range: [rows=1..10, cols=Month,Revenue]
x: Month
y: Revenue
Invalid:
type: line
data: [cols=Month,Revenue, rows=(Jan,120),(Feb,180)]
range: [rows=1..2]
x: Month
y: Revenue
When range limits columns, the fields used by the chart must exist within the slice.
Invalid:
type: line
source: #revenue
range: [cols=Month,Revenue]
x: Month
y: Profit
In this case, Profit is not available within the range.
The renderer must emit an error.
Each row in rows must have the same number of values defined in cols.
Valid:
type: bar
data: [cols=Product,Revenue, rows=("Product A",120),("Product B",80)]
label: Product
value: Revenue
Invalid:
type: bar
data: [cols=Product,Revenue, rows=("Product A",120),("Product B")]
label: Product
value: Revenue
Fields such as label, value, x, y, series, and size-value must point to existing columns.
Invalid:
type: bubble
data: [cols=Product,Revenue,Margin, rows=("Product A",120,30)]
x: Revenue
y: Margin
size-value: Customers
label: Product
In this case, Customers does not exist.
| Field | Default value |
|---|---|
variant |
default |
orientation |
vertical |
bg-color |
#ffffff |
border |
false |
subtitles |
none |
size |
defined by the renderer |
position |
ignored, unless the renderer supports absolute layout |
data-color |
automatic renderer palette |
A chart field value may be replaced by a placeholder that is resolved at render time.
This allows values to come from external sources — such as data sources, user preferences, or contextual state — without the chart spec needing to know where they originate.
A placeholder is a {{ and }} pair surrounding an identifier:
{{ identifier }}
Rules:
- The identifier must match
[A-Za-z_][A-Za-z0-9_-]*. - Spaces inside the braces are ignored:
{{foo}},{{ foo }}, and{{foo }}are all equivalent. - A placeholder must be the entire value of a field. Partial interpolation (e.g.
title: Sales {{period}}) is not allowed. - A placeholder may appear in any field value, except where explicitly restricted below.
A placeholder may replace the value of any field:
type: bar
title: {{ dynamicTitle }}
data: {{ salesData }}
label: {{ labelField }}
value: {{ valueField }}
data-color: {{ chartColors }}
size: {{ chartSize }}
When data: {{ identifier }} is used, the renderer resolves the placeholder into the complete [cols=..., rows=...] inline data syntax before parsing.
When source: {{ identifier }} is used, the renderer resolves the placeholder into a table identifier (#table-id) before resolving the table reference.
| Field | Placeholder resolves to |
|---|---|
data |
Full [cols=..., rows=...] inline data string |
source |
Table identifier (e.g. #my-table) |
range |
Full [rows=..., cols=...] range string |
label |
Column name |
value |
Column name or comma-separated list |
x |
Column name |
y |
Column name |
series |
Comma-separated list of column names |
size-value |
Column name |
title |
String |
type |
Chart type name (bar, line, etc.) |
variant |
Variant name |
orientation |
Orientation value |
data-color |
Space-separated list of colors |
bg-color |
Color value |
border |
true / false or true <thickness> |
position |
Position string (<x>x<y>) |
size |
Size string (<width>x<height>) |
subtitles |
Subtitle config string |
When a field that normally points to a column name (such as label, value, x, y, series, or size-value) uses a placeholder, the renderer must not check column existence at parse time. The check must be deferred until the placeholder is resolved.
The rule that a chart must use exactly one of data or source (Section 2) applies to the resolved values, not the placeholders.
Valid — exactly one resolves to a data source:
type: bar
data: {{ dynamicData }}
label: Product
value: Revenue
Valid — the other resolves to nil or empty:
type: bar
source: {{ dynamicSource }}
label: Product
value: Revenue
Invalid — both placeholders or one is a placeholder and the other is a static value:
type: bar
data: {{ dynamicData }}
source: {{ anotherSource }}
label: Product
value: Revenue
type: bar
data: [cols=Product,Revenue, rows=("Product A",120)]
source: {{ dynamicSource }}
label: Product
value: Revenue
The rule that range may only be used with source (Section 11.2) applies to the resolved value. If source uses a placeholder and range uses a placeholder, this is valid as long as the resolved source is a table reference. The renderer must defer this check.
Two different fields may reference the same placeholder identifier:
type: line
x: {{ timeField }}
y: {{ timeField }}
This is valid and expected — the renderer resolves both to the same value.
A single field may not mix a placeholder with static values:
type: line
x: Month
y: {{ dynamicY }}
Valid — unrelated fields are independent.
type: line
series: Store, {{ dynamicSeries }}
Invalid — series uses a comma-separated literal mixed with a placeholder. Use a single placeholder for the entire value instead.
Placeholder resolution occurs before chart construction and after the chart block is parsed into its key-value pairs.
The resolution order for a chart block is:
- Parse the chart block into key-value fields.
- Resolve all placeholders in field values.
- Parse the now-static field values according to their type rules (Section 5 for
data, Section 6 forsource, etc.). - Validate the fully resolved fields (Section 11).
- Render the chart.
This means a renderer never needs to handle placeholders during data parsing or validation — they are resolved to static values first.
A placeholder that replaces the data field resolves to a string that must conform to the inline data syntax defined in Section 5:
data: {{ myData }}
# resolves to:
data: [cols=Product,Revenue, rows=("Product A",120),("Product B",80)]
The renderer validates the resolved string using the same parser it uses for static inline data. There is no separate code path.
When rendering chart blocks for display in an editor:
- Placeholders should be visually distinct — for example, rendered as highlighted tokens (e.g.
{{ myData }}shown in a distinct color or with a badge) rather than as error states. - The editor must not attempt to validate fields that use placeholders for column existence. Deferred validation is acceptable.
When rendering chart blocks inside a spreadsheet cell:
- Placeholders may reference values from other cells. The resolution layer maps cell coordinates or named ranges to values.
- The same mutual-exclusivity and validation rules apply after cell-value resolution.
This specification does not prescribe how placeholders are resolved. The resolution mechanism is the responsibility of the implementation layer (e.g., data source bindings, cell references, template variables). The chart spec only defines:
- The syntax (
{{ identifier }}) - Where placeholders are valid
- How they interact with validation rules
A placeholder may fail to resolve — the identifier may be unknown, the external source may be unreachable, or the value may still be loading. The chart must not fail or refuse to render in any of these cases. Instead, each field type defines a fallback value.
If a resolution layer provides a cached or previously known value, that value takes priority over the default fallback. This allows implementations to persist resolved values (e.g., in frontmatter) so charts remain stable even when the original source is temporarily unavailable.
| Field | Fallback value |
|---|---|
data |
Empty inline data with no rows: [cols=, rows=] — the chart renders with no data points |
source |
Empty — the chart renders with no data points |
range |
No range — all rows and columns are used |
label |
First column of the resolved data |
value |
0 |
x |
0 |
y |
0 |
series |
Empty — no series are plotted |
size-value |
0 |
title |
Empty string — no title displayed |
type |
bar |
variant |
default (the type's default variant) |
orientation |
vertical |
data-color |
Renderer's default color palette |
bg-color |
Renderer's default background color |
border |
false |
position |
Ignored by the renderer |
size |
Renderer's default size |
subtitles |
none |
When resolving a placeholder, the implementation must follow this priority:
- Fresh resolved value from the external source (e.g., a live data source fetch).
- Cached or persisted value from a previous successful resolution (e.g., written to frontmatter or local storage).
- Default fallback from the table above.
This ensures a chart always renders with the best available data. A chart must never show an error state, loading spinner, or broken rendering due to an unresolved placeholder.
| Time | Source status | Behavior |
|---|---|---|
t=0 |
Not yet fetched | Renders with cached value (or fallback if no cache) |
t=1 |
Fetch in progress | Renders with cached value (or fallback) |
t=2 |
Fetch succeeds | Renders with fresh value; cache updated immediately |
t=3 |
Source unreachable | Renders with cached value from t=2; no visible change |
This means the chart never transitions from having data to having no data. At worst, it starts with a fallback and stays there until a fetch succeeds.
| Month | Revenue | Profit | Customers |
|-------|--------:|-------:|----------:|
| Jan | 120 | 30 | 400 |
| Feb | 180 | 45 | 520 |
| Mar | 150 | 35 | 480 |
| Apr | 220 | 60 | 700 |
| May | 260 | 70 | 820 |
{: #monthly-metrics }type: line
variant: smooth
title: Monthly revenue
source: #monthly-metrics
range: [rows=1..5, cols=Month,Revenue]
x: Month
y: Revenue
data-color: #6538fe
bg-color: #ffffff
border: true 1
size: 700x300
subtitles: bottom
type: bubble
title: Revenue, profit, and customers
source: #monthly-metrics
range: [rows=1..5, cols=Month,Revenue,Profit,Customers]
x: Revenue
y: Profit
size-value: Customers
label: Month
data-color: #6538fe #786fe6 #7375ef #9d8cff #b8a8ff
size: 700x400
subtitles: right