ECharts
echarts fence. Hugo validates them, and bundled ECharts draws charts that follow the color scheme.An echarts fence contains an ECharts option object in YAML or JSON. It contains data, not code.
Use it for quantitative charts with axes, series, and a legend.
Use Mermaid for relationships and flows. Use Infographic for order and hierarchy.
Hugo parses options at build time. Invalid input warns and preserves readable source.
The browser draws charts with the theme’s bundled ECharts. Only pages that use it load the runtime.
Shortest form
A bar chart needs xAxis, yAxis, and series. This chart shows page counts for the six documentation sections.
Both formats are supported. YAML is shorter because it needs no quotes or commas. Incorrect indentation or an array instead of a map warns, identifies the source line, and shows the source instead of a blank chart.
Multiple line series
series is an array. Add an entry for each line. legend lets readers hide a series.
This chart shows PostgreSQL major release years and the end-of-support years from the community’s five-year policy.
Quote version numbers. YAML reads unquoted 10 and 9.6 as numbers. Category-axis labels must be strings.
Pie and doughnut charts
Give radius two values to create a doughnut chart. This example groups OINK’s 29 shortcodes by purpose.
{b}, {c}, and {d} are ECharts placeholders for name, value, and percentage.
Use them in a string. No function is needed.
Height and full width
height defaults to 400px and accepts px rem em vh vw %.
full=true removes the reading-column limit and fills the content area. Use it for charts with many points or long labels.
Invalid heights such as 360 and 36pt warn and use the default 400px.
Light and dark
Without theme, charts use the reader’s current color scheme. They redraw in place when the scheme changes, without reloading the page.
Charts resize when their containers resize. Switch this page to dark mode to change each chart’s background and text.
A fixed theme keeps the same colors in both modes:
dark is the only built-in runtime theme. Register other ECharts themes with echarts.registerTheme() before naming them here.
Unless branding requires a fixed theme, omit theme so charts follow the site.
Callbacks with $fn:
A fence contains data and cannot contain JavaScript.
If an option needs a function, such as a tooltip formatter or data-dependent color, use "$fn:name" in the options.
Register the name on window.OinkEchartsFunctions:
Hover over a bar to see the tooltip sentence from the function.
Unregistered names resolve to undefined. The chart draws as if the option were absent, without build or runtime warnings.
Keep the script beside the fence so they change together.
The script is site code and needs code review. If string templates ({b}, {c}, {d}) can express the formatting, no function is needed.
Where the data lives
Fence bodies are literal text. Hugo does not expand shortcodes, front matter variables, or data/ files inside them.
Write the numbers in the fence. Data cannot be shared this way, but Git stores the chart with its data and shows changed numbers.
Do not chart data that changes frequently, such as version matrices or asset lists.
Use a table or a data/-driven component on a release page.
Output
| Output | Shape |
|---|---|
| HTML | A canvas container inside <div class="td-echarts"> plus an application/json options block; the local ECharts draws it |
No chart; the fence source inside <pre class="td-echarts-source"> |
|
| Markdown | The echarts fence and its option source, kept as written |
| RSS | Same as print — source only |
Explain the chart’s information in prose. Print and RSS do not include the chart.
Parameter reference
The fence attribute line (```echarts {…}):
style, on*, and unknown attributes warn and are ignored.
If a fence body does not parse to a YAML/JSON map, it warns and displays the source.
ECharts defines the option keys in its official option manual.
ECharts has no site-level parameter. It needs no switch in hugo.yml and loads only on pages that use it.
Limits
- Fences cannot contain JavaScript. Use
$fn:for functions. Unregistered names resolve toundefinedwithout an error. - Fences cannot read external data. They cannot access
data/, front matter, or shortcodes. Write the numbers in the fence. - Print and RSS include only the source. State the conclusion in prose.
- Quote category-axis values such as
10,9.6,on, andyes. YAML can convert them to numbers or booleans. - Use line styles or marker shapes as well as color to distinguish series. Check legend contrast in both color schemes.
Related
- Infographic — structure and order, not statistics
- Tables — for few values that must be read exactly
- Mermaid — relationship and flow diagrams
- Code blocks — the general rules for fence attribute lines