Charts That Live Inside Your Markdown Tables

You've written a README with a table of numbers and thought, "this would be so much clearer as a chart." Then you remember that means generating an image, committing it, and redoing the whole thing every time a number changes. MarkVis takes a different approach: you write the table, and it draws the chart. Change a number, the picture changes.

What It Does

MarkVis is a tool that turns a fenced code block into a chart. You tag the block with chart (or markvis, or vis), put your numbers inside, and MarkVis renders an SVG. The project supports thirteen chart kinds: bar, line, area, scatter, pie, hist, heatmap, funnel, waterfall, radar, gauge, sankey, and treemap. You can specify a theme and palette if you want to change the look, but those are optional.

The design has a nice fallback built in. If the chart can't draw, you still see the table. Text like N/A in a measure cell throws an error (E_BAD_NUMBER) rather than silently treating it as zero—and a blank measure cell means missing data, not zero. That distinction matters more than you'd think when you're dealing with real datasets.

This is actually a rewrite. The original MarkVis dates back to 2017, when it was a renderer that hit GitHub Trending. The new version (2.x, which replaces the old 0.0.13 d3 renderer—that one still lives in legacy/) is built for both people and AI. There's a plugin for remark and one for markdown-it, and both return the picture and the data table together.

Why It's Cool

• The source of truth is text. Your chart is a code block in a Markdown file. It diffs cleanly, it lives in version control like everything else, and there's no binary image to regenerate. When someone reviews your PR, they see the numbers change, not just a swapped-out PNG.

• The table stays visible. This is the part I like most. If rendering fails—bad data, unsupported type, whatever—the reader still gets the raw table. You don't lose information when the picture breaks. That's a genuinely thoughtful failure mode.

• bake is the pragmatic bit. Running npx markvis bake README.md writes an image next to the file and adds a Markdown image reference so GitHub can display it. The code block stays put. Run it again and nothing happens if nothing changed. For anyone who's ever committed a stale chart, this is the feature you'll actually use.

• It's built with AI in mind. There's a skills/markvis/SKILL.md file and an llms.txt. Point a model at those, and it should write only the fields listed—no invented type IDs, no PNGs. Given how often LLMs hallucinate chart configs, constraining the surface area like this is sensible.

• Validation is a first-class command. npx markvis check notes.md checks every chart block in a file and exits non-zero if any block is invalid. That's the kind of thing you can drop into CI without thinking twice.

The library API is small and honest about errors. parseMarkdown returns an object with an ok flag; if it's false, parsed.table still has your rows, and parsed.error.code is stable. No mystery exceptions.

How to Try It

The fastest path is the Play page—paste a block at markvis.js.org/play. No install required. Here's the example from the README:

markvis: 2
type: bar
title: Mar led Midtown box office at 9.2k tickets
unit: tickets
x: month
y: tickets

month,tickets
Sep,5200
Oct,6100
Nov,7800
Dec,8500
Jan,4800
Feb,7200
Mar,9200
Apr,6900

To use it locally:

npm install markvis
npx markvis bake README.md

bake writes the picture and adds the image reference. npx markvis check notes.md validates your blocks. Note that you omit markvis for version 2, and any other version is rejected.

If you're wiring it into a Markdown site, there are plugins for both markdown-it and remark. Both return the SVG and the data table in the HTML output. For the markdown-it route:

import MarkdownIt from "markdown-it";
import markdownItMarkvis from "markvis/markdown-it";

const html = new MarkdownIt({ html: true })
  .use(markdownItMarkvis)
  .render(markdown);

If you're using it with an AI assistant, point the model at skills/markvis/SKILL.md or llms.txt.

The repo is at github.com/geekplux/markvis.

Final Thoughts

MarkVis is best suited to people who write documentation, READMEs, or notes in Markdown and want charts to stay in the same file as their data. It's not trying to replace a full charting library—it's trying to make the common case (a table of numbers that should be a bar or line chart) frictionless. The fallback behavior, the idempotent bake, and the stable error codes suggest someone who's actually maintained documentation and gotten tired of the usual pain. If that's you, it's worth a look.

Follow @githubprojects for more developer tools and open source projects.