Markdown tables are excellent for exact values, but a bar chart makes comparisons visible immediately. Mermaid can keep the chart as text inside the same .md file as the surrounding explanation. There is no separate spreadsheet or image to update: change the values in the fenced block and render the document again.
Mermaid's XY chart syntax is the most direct way to create a conventional bar chart. Mermaid currently documents the diagram as xychart, while some deployed renderers—including the version used by mdview.io at the time of writing—still recognize its earlier xychart-beta identifier. The examples below use xychart-beta so they render in mdview.io today.
Add a fenced code block whose language is mermaid, then begin the diagram with xychart-beta:
The important lines are:
title supplies the chart heading.x-axis defines one category for each bar.y-axis adds a label and explicit numeric range.bar provides values in the same order as the categories.Keep the number of categories and values equal. If the x-axis lists five days, the bar series should contain five numbers.
Recent Mermaid releases can display values on bars through showDataLabel configuration. That option is not available in every deployed renderer. For a portable technical document, include the exact values in a compact table below the chart instead of relying on labels that may disappear after publishing.
| Environment | Builds |
|---|---|
| Development | 72 |
| Staging | 34 |
| Production | 18 |
Because renderer versions vary, preview the chart wherever the Markdown will ultimately be read. A platform with an older Mermaid release may require xychart-beta or ignore newer configuration options.
An XY chart can contain a bar series and line series together:
This is useful for showing actual values against a threshold or target. Explain both series in the surrounding prose because not every renderer provides a detailed legend, and color alone should not carry the meaning.
Quote category labels containing spaces:
Short labels work best. If categories require full sentences, use a table or explain abbreviations below the chart. A narrow reading column cannot make ten long labels readable merely because the syntax is valid.
Starting a bar chart above zero can visually exaggerate differences. For ordinary comparisons, use zero as the lower bound:
y-axis "Latency (ms)" 0 --> 500Set the upper bound slightly above the largest value so the tallest bar has room. Choose units in the axis title—requests, milliseconds, percent, or dollars—rather than forcing readers to infer them.
Mermaid Gantt diagrams also use horizontal bars, but they represent tasks across time. Use xychart when comparing numeric categories such as services, regions, or monthly totals. Use gantt when bar position and length describe a schedule.
If the chart does not render, check these points:
mermaid, not markdown or text.xychart-beta on mdview.io today, or xychart in current Mermaid documentation.A basic Markdown renderer may display the entire block as code even when the syntax is correct. Open it in mdview.io to render the bar chart inside the document and check it beside the table or explanation it supports.
A chart communicates shape; a table communicates exact values. For reports and technical decisions, consider placing a small source table below the chart. Readers can verify exact numbers, the chart remains accessible when diagram rendering is unavailable, and future editors have a clear record of what each bar represents.