DEV Community: oubakiou

Rendering Charts Beyond Mermaid's Reach with Vega-Lite and Embedding Them in Markdown (via LLM Skills)

oubakiou — Tue, 30 Jun 2026 04:34:02 +0000

AI agents like Claude Code and Codex can write code, polish documentation, and automate complex tasks. But ask them to "make a scatter plot of this data" or "show the trend as a heatmap," and they hit a wall. Mermaid tops out at basic bar charts and pie charts — statistical visualization is outside its scope.

dataviz-svg is a skill built to fill that gap. It generates SVG charts from Vega-Lite declarative JSON specs and embeds them directly into Markdown documents.

Where Mermaid Falls Short

Mermaid is a great tool, but it excels in a different domain.

Mermaid's strengths	dataviz-svg's strengths
Flowcharts, sequence diagrams, ER diagrams	Scatter plots, heatmaps, histograms
State diagrams, Gantt charts	Box plots, area charts, bubble charts
Simple bar charts with a few data points	Charts with 20+ data points
Structural diagrams in general	Multi-axis encoding (x, y, color, size)

In short: Mermaid is for structural diagrams, dataviz-svg is for data-driven statistical visualization. When an agent can use both, the expressiveness of its documentation output improves dramatically.

Supported Chart Types

An example actually generated from the skill

dataviz-svg inherits the full expressiveness of Vega-Lite, so the range of supported charts is broad. Check out the official Vega-Lite gallery to see what's possible at a glance.

Bar charts — vertical, horizontal, grouped, stacked (including 100% stacked)
Line charts — single series, multi-series (with strokeDash for print-friendly output)
Scatter plots — basic scatter, bubble charts (size + color + log scale)
Area charts — stacked area, streamgraph
Heatmaps — 2D grid with overlaid text layers
Histograms — distribution via binning
Box plots — quartile display
Pie / Donut charts — donut variant via innerRadius
Layered charts — line + point + text label overlays
Facet / Concatenation — small multiples, horizontal/vertical multi-chart layouts

How It Works

Tech Stack

The core of dataviz-svg is simple. Vega-Lite and Vega are bundled into a single ESM file (~1.6 MB) with Vite, so it runs on Node.js alone.

Vega-Lite JSON spec
    ↓ compile()
Vega spec
    ↓ Vega runtime
SVG string
    ↓ writeFileSync
output.svg

No native dependencies like canvas or puppeteer. No additional npm install needed. The bundle ships with the skill, so it works right after installation.

Execution Flow from the Agent's Perspective

When an agent uses this skill, it follows 5 steps:

Understand data and visualization requirements — identify the input data (inline values / CSV / JSON), chart type, and axis/color mappings
Create a Vega-Lite JSON spec — write the spec as a JSON file, referencing the bundled pattern collection
Render the SVG — run render-svg.sh to generate the SVG
Embed in Markdown — reference with ![Chart Title](./assets/chart.svg)
Review and adjust — inspect the SVG, tweak label angles or color scales, and re-render

From the user's perspective, you just say "turn this data into a heatmap" and the agent handles everything — spec creation, rendering, and document embedding — end to end.

Example: Visualizing Sales Data

For example, to create a bar chart of quarterly sales data, the agent generates a Vega-Lite spec like this:

{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "width": 400,
  "height": 300,
  "background": "white",
  "data": {
    "values": [
      { "quarter": "Q1", "sales": 120 },
      { "quarter": "Q2", "sales": 185 },
      { "quarter": "Q3", "sales": 210 },
      { "quarter": "Q4", "sales": 165 }
    ]
  },
  "mark": "bar",
  "encoding": {
    "x": { "field": "quarter", "type": "ordinal" },
    "y": { "field": "sales", "type": "quantitative" },
    "color": { "field": "quarter", "type": "nominal" }
  }
}

Pass this to render-svg.sh and an SVG is generated — no browser required.

Design Trade-offs

Practicality comes first. Here are the deliberate trade-offs:

SVG only: No PNG/PDF support. Eliminating native dependencies (canvas / sharp) means zero setup friction
Static output only: Vega-Lite's interactive features (hover, zoom, selection) don't carry over to SVG
No font embedding: Relies on system fonts. sans-serif is the safest choice
No canvas package: Text bounding box calculations are approximate, which may cause slight misalignment with long CJK (e.g., Japanese) labels

These are intentional. The top priority is "works immediately in any environment, with no extra installation."

Installation

# For Claude Code
gh skill install oubakiou/skills dataviz-svg --agent claude-code --scope project

# For Codex
gh skill install oubakiou/skills dataviz-svg --agent codex --scope project

The only prerequisite is Node.js 18 or later. Vega and Vega-Lite are bundled, so no separate installation is needed.

Summary

dataviz-svg is laser-focused on one thing: giving AI agents the ability to create data visualizations.

Generates statistical charts that Mermaid can't handle, powered by Vega-Lite
No browser, no extra dependencies — just Node.js
The agent handles the entire pipeline: spec creation, rendering, and document embedding

"Turn this data into a chart." — With that single request, the agent picks the right chart type, generates it, and embeds it in your document. Naturally integrating data visualization into the AI agent workflow — that's what dataviz-svg is for.

Your LLM reads the whole file. It doesn't have to.

oubakiou — Fri, 19 Jun 2026 12:05:00 +0000

Coding agents read specs, design docs, and long READMEs every day. Most of the time, they only need a few sections. Yet they load the entire file into context.

The hidden cost of "just read the file"

Here's a scenario that plays out constantly. You ask your agent to check the error handling section of a 5,000-line API spec. The agent opens the file, reads all 5,000 lines into its context window, finds the 80 lines it needs, and answers your question.

The result is correct. But the agent also consumed a large number of tokens on the 4,920 lines it didn't need. Repeat this for every file read in a session, and the waste compounds fast.

The cost isn't just tokens. A context window stuffed with irrelevant content makes the agent's answers worse.

What humans do differently

When a human picks up a 300-page technical book, they don't read cover to cover to find the chapter on authentication. They flip to the table of contents, scan the chapter titles, and jump to page 47. LLMs can do the same thing.

Markdown is already structured

Markdown documents have a built-in structure: headings. A # Title followed by ## Section A followed by ### Subsection A.1 creates a hierarchy that mirrors a book's table of contents.

Split a Markdown file at heading boundaries, and you get a natural "table of contents + sections" structure. Each heading starts a new section, the heading text becomes the index entry, and the section number becomes the address.

This is the idea behind md2idx, a CLI tool.

How to use md2idx

md2idx converts a Markdown file into JSON with two fields:

index: a numbered table of contents where each line is <# markers for depth> <serial>. <heading text>
sections: a flat array of raw Markdown strings, one per heading

$ npx md2idx spec.md | jq -r '.index'
# 0. API Specification
## 1. Authentication
## 2. Endpoints
### 3. GET /users
### 4. POST /users
## 5. Error Handling
## 6. Rate Limiting

The serial numbers match the array indices. To read the Error Handling section:

$ npx md2idx spec.md | jq -r '.sections[5]'
## Error Handling

When a request fails, the API returns a JSON error object with...
(just the content of that one section)

To read a heading and all its children together:

$ npx md2idx spec.md | jq -r '.sections[2:5][]'
# Endpoints, GET /users, and POST /users — all 3 sections

For a 5,000-line spec where the agent needs 2 sections, context usage goes from ~5,000 lines to ~100 lines (20-line index + 80 lines of content). Depending on the document and which sections are needed, the reduction is typically 80–98%.

The output is designed to work with jq. One-line JSON by default (pipe-friendly), --pretty for formatted output. Reads from a file argument or stdin.

Why not just grep for headings?

grep -nE '#{1,6} ' spec.md gives you a list of headings. For simple cases, that works. But md2idx covers problems that grep can't solve:

Section body retrieval: grep only returns heading lines. To get the body, you need to calculate the line range and use Read with offset/limit. With md2idx, jq '.sections[N]' is all it takes
Setext headings (=== / ---): invisible to grep's # pattern
# inside code fences: grep returns false positives. md2idx skips fenced blocks
Inline markup: grep includes [link](url) etc. as-is. md2idx strips markup in the index while preserving it in section content

Automate with a Claude Code skill

Skill details (SKILL.md)

With the md2idx-read skill, the agent autonomously handles everything from fetching the index to selecting sections.

The agent checks the file size and, if large, calls md2idx to fetch the index
It reads the index and identifies which sections are relevant to the current task
It retrieves only those sections via jq slicing
If more sections are needed, it goes back to step 3 (the index is already in context)

# install the skill
gh skill install oubakiou/md2idx md2idx-read --agent claude-code --scope project

# or with npx
npx skills add oubakiou/md2idx --skill md2idx-read --agent claude-code --yes

Once installed, the agent uses the skill proactively whenever it encounters a large Markdown file. No manual invocation needed — it reads the index first, picks sections, and skips the rest.

A fallback is included. If md2idx isn't available (network-restricted environments, permission issues), it falls back to grep for headings and Read tool with offset/limit. Less accurate, but functional.

Try it now

# read the index of any Markdown file
npx md2idx README.md | jq -r '.index'

# grab a specific section by number
npx md2idx README.md | jq -r '.sections[2]'

# search within a section
npx md2idx data.md | jq -r '.sections[4]' | grep Tokyo

# global install
npm install -g md2idx

md2idx has zero external dependencies — a self-contained line scanner, not a Markdown AST parser. It handles ATX headings (# style), setext headings (=== / --- underlines), code fence skipping, and inline markup stripping.

md2idx is MIT-licensed and fully open source. If your LLM agents are reading entire large Markdown files, give it a try:

GitHub repo →
npm → npx md2idx your-file.md | jq -r '.index'
Claude Code skill → gh skill install oubakiou/md2idx md2idx-read

If you've tried it in your agent workflow, I'd love to hear how it went — drop a comment below or open an issue on GitHub.

The next bottleneck after AI writes your code is reviewing the docs it writes

oubakiou — Wed, 17 Jun 2026 03:43:15 +0000

Coding agents draft specs, architecture docs, changelogs, and README updates in seconds — but a human still has to judge the quality of all that output.

The bottleneck shift

A year ago, the typical workflow was: you write a spec, you get comments, you revise, then you implement and get code review. Humans did most of the writing and coding. Now, agents produce first drafts of design docs, API references, runbooks, and onboarding guides — and they do it in seconds.

Code implementation and code review can now be handled by agents, so those are no longer the bottleneck. What surfaced instead is the step right before: document review. A human has to read 2,000 lines of generated markdown and decide what's wrong. The writing part got dramatically faster. LLMs can assist with document review too, but compared to code implementation and code review, the human judgment required is still larger.

This asymmetry compounds fast. Every agent-assisted project now has a stack of "needs human review" documents growing in a shared folder. If you're running multiple agent loops in parallel — one for the spec, one for the implementation plan, one for the test strategy — review becomes a pipeline stall. GitHub PRs remain the right tool when you need third-party review. But the step before that — the fast local self-review loop where you and your agent iterate on a draft — doesn't belong in a PR. Branching, diffing, and assigning reviewers is a lot of process for a first draft the agent wrote in seconds.

Why prose feedback is lossy

The most common workaround today is to have the agent read the document and then fix things based on natural-language feedback:

"The error handling in section 3.2 is too vague — be specific about what happens on timeout."

This looks reasonable. The agent reads it, searches for something about error handling, and makes a change. But several things go wrong:

Position is ambiguous. If section 3.2 has three paragraphs about error handling, which one did the reviewer mean? The agent guesses, and sometimes guesses wrong.

Context is lost. The reviewer was looking at a rendered document — they saw the Mermaid diagram, the table layout, the code blocks with syntax highlighting. The prose feedback carries none of that visual context.

Round-trips are vague. The agent applies a fix. Did it address the right spot? The reviewer pastes the updated draft back into the chat. No diff. No anchoring. Another round of guessing.

The fundamental problem: prose feedback loses the structure the reviewer had in mind. The reviewer knows which text range they're commenting on — but that spatial information is discarded the moment they express it in natural language.

Feedback as a machine-readable artifact

What if the reviewer's comments came back as structured JSON, with every comment anchored to a precise location in the source markdown?

That's what MDXG Redline (online demo) produces. The reviewer selects any text range in a rendered markdown document, leaves an inline comment, and on export the tool writes a JSON file like this:

{
  "document": "api-spec.md",
  "docHash": "a1b2c3d4e5f6a7b8",
  "exportedAt": "2026-06-15T10:30:00.000Z",
  "comments": [
    {
      "id": "f3a1c8b2",
      "quote": "The service retries up to 3 times",
      "comment": "Specify the backoff strategy — is it exponential? Fixed interval? This matters for downstream timeout config.",
      "headingPath": ["## 3. Error Handling", "### 3.2 Retry Policy"],
      "sourceLine": 142,
      "created": "2026-06-15T10:28:11.000Z"
    }
  ]
}

Every comment carries:

quote — the exact text the reviewer selected (human-readable reference)
comment — what the reviewer wrote
headingPath — the heading ancestry, from shallowest to deepest (["## 3. Error Handling", "### 3.2 Retry Policy"]), so the agent can navigate the document hierarchy
sourceLine — the 1-origin line number in the source markdown, so the agent can jump straight to the right spot

(The actual export also includes blockId, startOffset, and endOffset — internal anchoring fields used for round-trip re-import into the next review round. The four fields above are the ones your agent needs.)

No guessing, no ambiguity. The agent reads the JSON, opens the source file, goes to line 142, and applies the feedback directly. The feedback JSON is a plain file on disk — any agent that can read JSON and edit files can consume it, regardless of framework or provider.

The loop in practice

MDXG Redline is designed around a review loop where an agent and a human pass a document back and forth:

The agent uses the CLI to generate a <name>-<hash>-review.html file from the markdown — a self-contained HTML file that renders the document with syntax highlighting, diagrams, and math.
The CLI auto-launches the reviewer's browser.
The reviewer reads the rendered document, selects text ranges, and leaves inline comments. One click writes <name>-<hash>-feedback.json to the same folder.
The agent monitors in the background, automatically picks up the JSON, and applies the feedback.

Each revision gets a unique hash in the filename, so review/feedback pairs for different revisions never collide.

For Claude Code and Codex users, there's a md-review skill that automates the entire loop — HTML generation, waiting for feedback, and applying revisions:

SKILL.md

# install the skill
gh skill install oubakiou/mdxg-redline md-review --agent claude-code --scope project

# then just tell the agent:
# "please request a review for spec.md"
# or invoke the slash command directly:
# /md-review README.md

The skill is a convenience wrapper. Since the feedback JSON is a plain file, the loop works with any agent — you can wire it into a custom LangChain pipeline or a simple shell script that polls for the JSON.

What it renders

MDXG Redline isn't just a review overlay — it's a markdown rendering engine packed into a single standalone HTML file with no backend and no dependencies.

Smartphone support — On mobile screens, the UI switches to a layout with a footer bar for TOC, Comments, and Search. You can review and comment from your phone — no need to wait until you're back at your desk.

Syntax highlighting for ~235 languages — The CLI auto-detects which languages your document uses and injects only those Shiki grammars, keeping the file lean.

Mermaid diagrams and KaTeX math — Fenced `mermaid blocks render as SVGs; $...$ / $$...$$ math renders via KaTeX. Both are auto-detected and injected only when present.

Word-style stacked pages — The document splits at H1/H2 boundaries into paper-like sheets you scroll through vertically, with a sidebar for navigation. Footnotes and left-hand keyboard navigation are also built in.

See the full feature list in the README for details.

Try it in 30 seconds

No install needed — open mkdn.review and load any public GitHub raw URL. Here's a one-click example that loads the project's own README:

Open this README on mkdn.review →

Select any text in the rendered document, leave a comment, and click "Copy as JSON" to see the structured output.

Want to try with your own project? Just replace the URL: mkdn.review/?url=<your-github-raw-url>.

Local review — if you have Node.js:

npx mdxg-redline your-draft.md

This generates a review HTML in the same directory and opens it in your browser. The generated file is fully self-contained — you can email it, drop it in Slack, or put it in a shared folder. Everything stays local; no content or comments are sent anywhere.

Privacy note: The standalone and CLI builds enforce connect-src 'none' via CSP — your document body and comments cannot leave the browser. The online version (mkdn.review) likewise never sends your content or comments anywhere — the only network request is the ?url= fetch, which retrieves public raw content from a short allowlist (GitHub raw, Gist raw).

It's an MDXG implementation

MDXG Redline is a third-party implementation of the Markdown Experience Guidelines (MDXG) by Vercel Labs — the read-only Viewer rendering profile, with a review layer (inline commenting + structured JSON export) added on top. See the compliance table for details.

MDXG Redline is MIT-licensed and fully open source. If reviewing agent-generated documents is a bottleneck in your workflow, give it a try:

Try the online viewer →
GitHub repo →
npm → npx mdxg-redline draft.md
Claude Code skill → gh skill install oubakiou/mdxg-redline md-review (usage details)

If you've tried it with your agent workflow, I'd love to hear how the structured JSON feedback format worked for you — drop a comment below or open an issue on GitHub.