How to Add Interactive Charts to Markdown with Vega-Lite

Markdown handles text, code, and diagrams well. But what about data visualization? If you need a bar chart, line graph, or scatter plot in your document, you typically have to create it in a separate tool, export it as an image, and embed it. Vega-Lite changes that.

Quick Answer: Vega-Lite lets you embed interactive charts directly in Markdown using a fenced code block with the vega-lite tag and a JSON specification. It supports bar, line, scatter, area, and grouped charts out of the box. The grammar covers over 40 chart types and reduces visualization code by up to 90% compared to writing raw D3.

What Is Vega-Lite?

Vega-Lite is a high-level grammar for interactive data visualizations. You describe a chart using a JSON specification, and the library renders it as an interactive SVG. It is declarative: you say what you want to show, not how to draw it.

Vega-Lite is developed by the University of Washington’s Interactive Data Lab and is widely used in data science, journalism, and academic publishing. The library has over 9,000 GitHub stars and is used by teams at Apple, Google, and The New York Times for production data visualizations.

How Do You Embed a Vega-Lite Chart in Markdown?

In editors that support it (like edtr.md), you embed a Vega-Lite chart as a fenced code block with the vega-lite language tag:

```vega-lite
{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "data": {
    "values": [
      {"category": "A", "value": 28},
      {"category": "B", "value": 55},
      {"category": "C", "value": 43},
      {"category": "D", "value": 91}
    ]
  },
  "mark": "bar",
  "encoding": {
    "x": {"field": "category", "type": "nominal"},
    "y": {"field": "value", "type": "quantitative"}
  }
}
```

This renders as an interactive bar chart directly in the preview pane.

What Chart Types Does Vega-Lite Support?

Bar Chart

{
  "mark": "bar",
  "encoding": {
    "x": {"field": "category", "type": "nominal"},
    "y": {"field": "value", "type": "quantitative"}
  }
}

Line Chart

{
  "mark": "line",
  "encoding": {
    "x": {"field": "date", "type": "temporal"},
    "y": {"field": "price", "type": "quantitative"}
  }
}

Scatter Plot

{
  "mark": "point",
  "encoding": {
    "x": {"field": "weight", "type": "quantitative"},
    "y": {"field": "height", "type": "quantitative"},
    "color": {"field": "species", "type": "nominal"}
  }
}

Area Chart

{
  "mark": "area",
  "encoding": {
    "x": {"field": "date", "type": "temporal"},
    "y": {"field": "count", "type": "quantitative"}
  }
}

Should You Use Inline Data or External Data in Vega-Lite?

The examples above use inline values arrays. For larger datasets, Vega-Lite supports loading data from URLs:

{
  "data": {"url": "https://example.com/data.csv"},
  "mark": "line",
  "encoding": {
    "x": {"field": "date", "type": "temporal"},
    "y": {"field": "value", "type": "quantitative"}
  }
}

For Markdown documents, inline data is usually better because it keeps the document self-contained and works offline.

How Do You Add Titles and Labels to a Vega-Lite Chart?

{
  "title": "Monthly Revenue",
  "mark": "bar",
  "encoding": {
    "x": {"field": "month", "type": "ordinal", "title": "Month"},
    "y": {"field": "revenue", "type": "quantitative", "title": "Revenue ($)"}
  }
}

How Do You Style Colors and Group Categories in Vega-Lite?

Use the color encoding to distinguish categories:

{
  "mark": "bar",
  "encoding": {
    "x": {"field": "quarter", "type": "ordinal"},
    "y": {"field": "sales", "type": "quantitative"},
    "color": {"field": "region", "type": "nominal"}
  }
}

This creates a grouped bar chart with one color per region.

When Should You Use Vega-Lite vs Mermaid?

Use Case	Tool
Flowcharts, architecture	Mermaid
Sequence diagrams	Mermaid
Bar, line, scatter charts	Vega-Lite
Data-driven visualizations	Vega-Lite
Gantt charts	Mermaid
Statistical plots	Vega-Lite

Mermaid is for structural diagrams. Vega-Lite is for data visualization. They complement each other. See the full Mermaid diagrams in Markdown guide for flowchart and sequence diagram examples. If you are building complete reports that combine charts, tables, and narrative, the business reports with Markdown and Vega-Lite guide walks through a full quarterly report example.

Try It

Open edtr.md, create a fenced code block with the vega-lite tag, and paste any of the JSON specs above. The chart renders in the preview pane immediately. When you export to HTML, the chart is included as an interactive visualization.