Beyond Mermaid: Creating Rich Charts with Vega-Lite and Markdown

Why Charts Matter in Documentation

When you're explaining data to someone reading your docs, a picture beats a thousand words. Charts help readers spot trends, understand distributions, and grasp patterns at a glance. On June 30, 2026, as more teams automate their documentation and knowledge bases, the ability to embed rich visualizations directly in Markdown is becoming essential.

The challenge is that many chart tools were designed for either simplicity or power, but rarely both. You want something that's easy to generate, looks professional, and fits naturally into your documentation workflow.

What Mermaid Does Well (And Where It Stops)

Mermaid is excellent at what it does: flowcharts, sequence diagrams, Gantt charts, pie charts, and basic bar charts. If your chart needs look simple, Mermaid is the right choice. It's widely supported, easy to write, and renders in most Markdown environments.

But Mermaid wasn't designed for statistical visualization. Try to create a scatter plot showing the relationship between two variables. Try a heatmap showing intensity across categories. Try a box plot comparing distributions. Mermaid either can't do it or does it poorly. If you need something beyond Mermaid's set of built-in chart types, you're stuck.

That limitation matters because data visualization is increasingly common in technical documentation. Whether you're showing API response times, feature adoption rates, or user engagement patterns, you'll quickly outgrow what Mermaid can provide.

Introducing Vega-Lite: A More Powerful Approach

Vega-Lite is a declarative grammar for creating interactive visualizations. Instead of drawing your chart by hand, you describe it using JSON. You specify your data, map columns to visual properties (x-axis, y-axis, color, size), and Vega-Lite renders the visualization for you.

This approach has several advantages. First, it's flexible: Vega-Lite supports bar charts, line charts, scatter plots, heatmaps, box plots, area charts, and dozens of other types. Second, it's data-driven: you give it a dataset and tell it how to encode the data visually. Third, it integrates well with Markdown: you can embed Vega-Lite specs directly into your documentation.

Understanding Vega-Lite JSON Specifications

A Vega-Lite specification is a JSON object that describes a chart. Here's a simple example that creates a scatter plot:

{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "title": "Product Sales vs Marketing Spend",
  "data": {
    "values": [
      {"spend": 1000, "sales": 5000},
      {"spend": 2000, "sales": 8000},
      {"spend": 3000, "sales": 12000}
    ]
  },
  "mark": "point",
  "encoding": {
    "x": {"field": "spend", "type": "quantitative"},
    "y": {"field": "sales", "type": "quantitative"}
  }
}

The specification says: take the data provided, plot each row as a point, put the spend value on the x-axis and sales value on the y-axis. Vega-Lite handles the rendering.

You can make this far more complex: add colors, sizes, multiple layers, filtering, or interactive features. But even a simple spec like this covers use cases Mermaid can't handle.

Embedding Vega-Lite in Markdown

To embed a Vega-Lite chart in Markdown, you typically use a code fence with a special renderer. Some Markdown environments support vega-lite as a language identifier:

{"$schema": "https://vega.github.io/schema/vega-lite/v5.json", "data": {"values": [{"x": 1, "y": 2}, {"x": 2, "y": 4}]}, "mark": "line", "encoding": {"x": {"field": "x"}, "y": {"field": "y"}}}

Other platforms require you to use a service that renders Vega-Lite specs. Some documentation tools support Vega-Lite natively; others need a plugin or a wrapper.

The advantage over static images: these charts are interactive. Readers can hover to see exact values, zoom in on details, or toggle data series on and off.

Integration with AI and Automation

One reason Vega-Lite works well for AI-driven documentation is that the JSON format is easy for language models to generate. When you ask an AI agent to "create a chart showing this data," it can output a valid Vega-Lite spec without ambiguity.

This opens up new workflows. Imagine a documentation-generation skill that takes raw data and automatically generates appropriate visualizations, then embeds them in Markdown. Or a documentation pipeline that accepts new datasets and regenerates charts on demand.

AI agents can also choose the right chart type for your data. A language model can look at your dataset and decide: "This looks like a distribution — I'll use a histogram." Or "This is time-series data — I'll use a line chart." This removes the manual step of deciding which chart to use.

Building a Chart Generation Workflow

Step 1: Prepare Your Data

Gather your data in a structured format. JSON arrays work well, but CSV or other formats are fine too. Make sure each record has clear field names.

[
  {"month": "January", "revenue": 45000, "expenses": 32000},
  {"month": "February", "revenue": 52000, "expenses": 35000},
  {"month": "March", "revenue": 58000, "expenses": 38000}
]

Step 2: Design Your Visualization

Think about what story your data tells. Are you showing a trend? A comparison? A distribution? This determines your chart type.

Step 3: Generate the Vega-Lite Spec

Write the JSON specification, or use an AI tool to generate it. Specify the data source, the chart type, and how columns map to visual properties.

Step 4: Embed in Markdown

Insert the spec into a code fence in your Markdown document. Verify it renders correctly.

Step 5: Document the Chart

Write a short explanation of what the chart shows and why it matters. Context turns a visualization into information.

Common Chart Types and When to Use Them

Scatter plots work well for showing relationships between two continuous variables. Heatmaps excel at showing intensity across two dimensions. Box plots compare distributions across groups. Line charts track changes over time. Bar charts compare values across categories. The right choice depends on your data and the question you're answering.

Limitations and Tradeoffs

Vega-Lite is powerful, but it's not perfect for every use case. Very large datasets (millions of rows) can slow down rendering. Some specialized chart types fall outside Vega-Lite's scope. And Vega-Lite specs can get verbose for complex visualizations.

Also, not all Markdown viewers support Vega-Lite. GitHub's Markdown renderer doesn't natively support it, though GitHub-Flavored Markdown wikis and some documentation platforms do. If your audience reads your docs on platforms without Vega-Lite support, the charts won't render.

Conclusion

Vega-Lite fills an important gap in the documentation toolchain. It handles statistical visualization, integrates with Markdown, works well with AI-driven automation, and produces interactive charts. If you've outgrown Mermaid, it's a natural next step.

Merits

• Supports dozens of chart types beyond what Mermaid offers
• Declarative JSON format is straightforward and AI-friendly
• Interactive features like hover tooltips and zooming improve readability
• Embeds cleanly into Markdown without external image files
• Free and open source
• Works in browsers without requiring backend rendering

Demerits

• Not supported natively by all Markdown renderers (notably GitHub)
• Steeper learning curve than Mermaid for complex charts
• Large datasets can impact rendering performance
• Verbose JSON specs compared to other declarative chart languages
• Requires platform support to render; falls back to unrendered code blocks otherwise

Caution

The data, field names, and example values in this article are illustrative placeholders. Before using Vega-Lite in production documentation, test your charts on the platforms where your audience will view them. Some environments require additional configuration or plugins to render Vega-Lite. Always verify that interactive features like zoom and filtering work as expected. Proceed at your own risk and adapt the approach to your specific documentation platform and audience.

Frequently asked questions

• How do I convert an existing Mermaid chart to Vega-Lite?
• Can Vega-Lite handle real-time or streaming data?
• What's the performance impact of embedding many Vega-Lite charts on one page?
• How do I style Vega-Lite charts to match my documentation theme?
• Is Vega-Lite the same as Vega, and what's the difference?
• Can Vega-Lite generate printable charts for PDFs?
• How do I make Vega-Lite charts responsive on mobile devices?
• What chart types in Vega-Lite are best for comparing groups?

Tags

#dataviz #vega-lite #markdown #documentation #charts #visualization #json #webdev #tutorial #analytics