Markdown Charts: Bar, Line and Pie Charts with Mermaid
November 11, 2026 · 12 min read
Markdown Charts: Bar, Line, and Pie Charts in Plain Text
Markdown charts come from a renderer, not from Markdown itself. You type the data as text inside a fenced code block, usually a Mermaid block, and GitHub, GitLab, Obsidian or a live editor draws the chart. This guide shows working bar, line, pie and quadrant examples, where each renders, and what to do when nothing does.
Can You Make Charts in Markdown?
Not with Markdown alone. CommonMark covers text, lists, links and code, GitHub Flavored Markdown adds tables, and neither spec has a chart element. What you get instead is a convention: a fenced block tagged with a language name that the renderer recognizes and swaps for a picture.
Mermaid is the usual way to write markdown charts, because GitHub, GitLab and Obsidian all ship it. Its xychart type draws bar and line charts, pie draws pie charts, and quadrantChart plots points on a two-by-two grid. Everything else (Chart.js fences, Vega-Lite specs, exported images) depends on a plugin or on you hosting a file.
One naming trap: in Mermaid, graph is the keyword for a flowchart, so searches for markdown graphs often land on boxes and arrows rather than data. If that's what you want, our Mermaid diagrams guide covers flowcharts. This post sticks to charts that plot numbers.
How Do You Make a Bar Chart in Markdown?
A markdown bar chart starts as a mermaid fence whose first line is xychart-beta. Add a title, the categories for the x-axis in square brackets, a y-axis label with a min --> max range, and a bar line holding one number per category.
```mermaid
xychart-beta
title "Pull requests merged per month"
x-axis [Jan, Feb, Mar, Apr, May, Jun]
y-axis "Merged PRs" 0 --> 60
bar [18, 24, 31, 27, 42, 55]
```
That renders as six vertical bars, one per month, against a scale from 0 to 60:
A few syntax rules from the Mermaid XY chart docs prevent most parse errors:
- Text with a space needs double quotes. Single words like
Janorbugdon't. - The y-axis is always numeric. It can't hold categories.
- Skip the range (
y-axis "Merged PRs") and Mermaid works one out from the data. - Mermaid 11.10 dropped the beta label, so newer renderers also accept plain
xychart. We usexychart-betahere because older renderers only know that keyword, and new ones still accept it.
For long category names, flip the chart on its side with xychart-beta horizontal:
```mermaid
xychart-beta horizontal
title "Open issues by label"
x-axis [bug, docs, feature, question]
y-axis "Issues" 0 --> 40
bar [34, 12, 27, 8]
```
The categories now run down the left side and the bars grow to the right.
Line Graphs and Bar-Plus-Line Combos With xychart
Swap bar for line and the same block draws a markdown line graph. The x-axis can also be a numeric range instead of a list of categories, which suits time series like weeks or releases.
```mermaid
xychart-beta
title "Page load time by week"
x-axis "Week" 1 --> 8
y-axis "Seconds" 0 --> 4
line [3.4, 3.1, 2.9, 3.0, 2.4, 2.1, 1.9, 1.8]
```
You can stack several series in one chart. Put a bar and a line together to compare actuals with a target, and give each series a quoted name:
```mermaid
xychart-beta
title "Signups vs target"
x-axis [Q1, Q2, Q3, Q4]
y-axis "Signups" 0 --> 1200
bar "Actual" [420, 610, 790, 1050]
line "Target" [500, 650, 800, 950]
```
Each bar shows one quarter's signups, and the line traces the target across them. Series names only appear in a legend from Mermaid 11.17.0 onward. Older renderers accept the names but draw no legend, so say which series is which in the title or the sentence after the chart.
The docs list a few newer extras too, each with a minimum version. A showDataLabel setting prints each bar's value (documented for 11.14.0 and later), and line points can carry text labels from 11.16.0. You switch data labels on in a config block at the top of the fence:
```mermaid
---
config:
xyChart:
showDataLabel: true
---
xychart
x-axis [Q1, Q2, Q3, Q4]
bar [420, 610, 790, 1050]
```
Check what your platform runs before relying on these extras, because an older renderer ignores the setting or rejects the block.
Try it in the demo below, which holds a small bar-and-line chart. Edit a number on the left and the preview on the right redraws the chart.
Pie Charts and Quadrant Charts in Mermaid
Pie charts use their own pie block. Each slice is a quoted label, a colon and a positive number, and Mermaid works out the percentages. Adding showData after pie prints the raw values next to the legend:
```mermaid
pie showData
title Where support tickets came from
"Email" : 48
"Live chat" : 31
"Phone" : 12
"Forum" : 9
```
The Mermaid diagrams guide also covers pie syntax, so we'll move on to the quadrant chart, which most chart guides skip. It places named points on a grid split into four labeled boxes, which is handy for effort-versus-impact or risk matrices.
```mermaid
quadrantChart
title Feature requests by effort and impact
x-axis Low Effort --> High Effort
y-axis Low Impact --> High Impact
quadrant-1 Plan carefully
quadrant-2 Do first
quadrant-3 Fill-ins
quadrant-4 Skip for now
Dark mode: [0.25, 0.8]
CSV export: [0.3, 0.4]
SSO login: [0.8, 0.85]
Custom fonts: [0.7, 0.2]
```
Per the quadrant chart docs, quadrant-1 is the top right box and the numbering runs counter-clockwise, so quadrant-2 is top left. Point coordinates run from 0 to 1 on both axes, so scale your raw scores into that range first.
Where Do Markdown Charts Render?
A Mermaid fence only becomes a chart where the renderer ships Mermaid, and xychart and quadrantChart also need a reasonably recent release. Here's how the common places compare:
| Where | Mermaid charts | What to check |
|---|---|---|
| GitHub | Yes, in .md files, issues, PRs, discussions and wikis | Version unpublished, so run the info check below |
| GitLab | Yes | Current docs state Mermaid version 12 |
| Obsidian | Yes, in a mermaid code block | No version listed, so test an xychart in a note |
| Our editor | Yes, live in the preview | Paste the block and check the right pane |
| Plain CommonMark renderers | No | The block shows as code |
GitHub's diagram docs suggest a quick test: post a mermaid block that contains only the word info, and the rendered output shows the Mermaid version in use.
```mermaid
info
```
If the version predates a feature you need, such as the legend in 11.17.0, the chart either drops that feature or shows a parse error. For more on what GitHub renders in general, see our GitHub Markdown cheat sheet.
Chart.js and Other Plugin Fences Beyond Mermaid
Mermaid covers bar, line, pie and quadrant charts, plus a few specialist types such as Sankey and radar. For scatter plots, stacked areas or interactive tooltips, people reach for a charting library wired in through a plugin. These only render on the platform that has the plugin installed.
In Obsidian, the community Charts plugin adds a chart code block written in YAML:
```chart
type: bar
labels: [Mon, Tue, Wed, Thu, Fri]
series:
- title: Commits
data: [4, 7, 3, 9, 5]
```
VuePress sites can install the markdown-chart plugin, which supports six libraries including Chart.js, ECharts and Mermaid. Once Chart.js is enabled in the plugin options, you wrap a JSON config in a ::: chartjs container:
::: chartjs Weekly commits
```json
{
"type": "bar",
"data": {
"labels": ["Mon", "Tue", "Wed"],
"datasets": [{ "label": "Commits", "data": [4, 7, 3] }]
}
}
```
:::
Other routes exist too. Vega-Lite describes a chart as a JSON spec, MDX sites import a React chart component, and Jupyter or Quarto notebooks run code and save the figure. All of them tie your file to one toolchain. Our editor's preview doesn't render any of these plugin fences, and neither does GitHub. In VS Code, the Markdown Preview Enhanced extension draws Vega and Vega-Lite fences in its preview.
We prefer Mermaid for anything that lives in a repository. The same block renders on GitHub, GitLab and Obsidian with no setup, and the data stays readable in a diff.
Fallbacks When Your Renderer Has No Chart Support
Any viewer without Mermaid built in shows the fence as raw code. When you can't count on markdown charts rendering, you have three options.
Export the chart as an image. Build it in our Mermaid editor, which previews live and exports PNG or SVG, then host the file and link it by URL:

Keep the Mermaid source next to the image so you can regenerate it when the numbers change.
Draw the bars with Unicode blocks. The Full Block character (U+2588) and its partial-width siblings sit in the Block Elements range. Together they make a crude bar chart that survives anywhere a code block does:
Jan █████████ 18
Feb ████████████ 24
Mar ███████████████▌ 31
Apr █████████████▌ 27
May █████████████████████ 42
Keep it inside a code block so the font stays monospaced. Outside one, proportional fonts knock the bars out of line, and some fonts draw the half block at a different width.
Show the numbers as a table. A table gives exact values, works with screen readers, and renders in every GFM viewer. Our Markdown table guide covers alignment and formatting.
Picking a Markdown Chart Type for Your Data
Match the chart to the question your reader is asking:
- Comparing categories (sales by region, issues by label): a bar chart.
- Showing a trend over time (load time by week): a line chart.
- Showing parts of a whole that add up to 100%: a pie chart, ideally with five slices or fewer.
- Ranking items on two scales (effort and impact): a quadrant chart.
- Plan versus actual: bars plus a line in one xychart.
If your numbers already sit in a Markdown table, converting them takes a minute. The first column becomes the x-axis list, and each numeric column becomes one bar or line row, in the same order:
| Quarter | Actual | Target |
|---|---|---|
| Q1 | 420 | 500 |
| Q2 | 610 | 650 |
That table maps to x-axis [Q1, Q2], then bar [420, 610] and line [500, 650]. Set the y-axis range a little above your largest value so the tallest bar doesn't touch the top edge. We keep the table under the chart in docs, because readers who want exact figures can copy them from it.
Be clear about the limits. Mermaid's xychart draws bars and lines only, with no scatter, area or stacked bars, and its y-axis can't hold categories. If your data needs one of those, export an image from a charting tool or fall back to a table.
Quick Answers on Markdown Charts
Markdown charts work best when you treat them as data that happens to render. Write the numbers in a Mermaid block, check what your platform's renderer supports, and keep an image or table fallback for places that show raw code. Open our editor to test a bar or line chart in the live preview, or build one in the Mermaid editor and export it as SVG.