Vega-Lite Setup with Quarto

Important: Vega-Lite Lua Filter Required

Quarto does NOT have native Vega-Lite support out of the box. This project uses vega-lite.lua - a Quarto filter that enables Vega-Lite visualization rendering.

✅ What's Already Configured

vega-lite.lua - Custom Lua filter that processes Vega-Lite code blocks
_quarto.yml - Already configured to use the filter:
```
filters:
  - vega-lite.lua
```

🎨 How to Use Vega-Lite in Your Posts

Basic Usage

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

With Options

```{vega-lite}
#| echo: false
#| code-fold: true
{your vega spec}
```

Supported options:

echo: false - Hide the code, show only the visualization
echo: true - Show both code and visualization (default)
code-fold: true - Make code collapsible (collapsed by default)
code-fold: show - Make code collapsible but open by default

🔧 How the Filter Works

The vega-lite.lua filter:

Detects code blocks with class vega-lite
Includes Vega libraries (Vega, Vega-Lite, Vega-Embed) from CDN
Renders the specification using vegaEmbed() JavaScript
Handles code display options (echo, code-fold)

Libraries Loaded

vega@5 - Core Vega library
vega-lite@5 - Vega-Lite library
vega-embed@6 - Embedding library

📝 Migrating from Hugo Shortcodes

Hugo shortcode (OLD):

{{</* vega-lite id="chart-bar-in-bar" actions="true" */>}}
{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "mark": "bar",
  ...
}
{{</* /vega-lite */>}}

Quarto with Lua filter (NEW):

```{vega-lite}
{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "mark": "bar",
  ...
}
```

Key differences:

No need for id attribute - filter auto-generates unique IDs
No actions attribute - actions toolbar enabled by default
No load_vega frontmatter needed - filter includes libraries automatically
Just paste your Vega-Lite JSON spec inside the code fence!

🎯 Migration Steps for Vega Posts

Find Hugo shortcode:
```
{{</* vega-lite id="..." */>}}
```
Copy the JSON spec (everything between the shortcode tags)

Replace with code fence:

```{vega-lite}
{your JSON spec here}
```

Remove the load_vega: true from frontmatter (no longer needed)

🧪 Testing

After adding a Vega-Lite visualization:

Build: quarto render
Preview: quarto preview
Check:
- Visualization renders correctly
- Actions toolbar appears (export PNG/SVG/etc.)
- No errors in browser console
- Code display respects your echo/fold settings

📋 Example Post with Visualization

---
title: "My Vega-Lite Post"
date: "2024-03-15"
lang: en
categories:
  - dataviz
  - showcase
---

## Simple Bar Chart

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


## 🔗 Additional Resources

- [Vega-Lite Documentation](https://vega.github.io/vega-lite/)
- [Vega-Lite Examples](https://vega.github.io/vega-lite/examples/)
- [Quarto Filters Guide](https://quarto.org/docs/extensions/filters.html)

## ⚠️ Troubleshooting

**Visualization not rendering:**
- Check that `vega-lite.lua` exists in the project root
- Verify `filters: - vega-lite.lua` is in `_quarto.yml`
- Ensure JSON spec is valid (test at https://vega.github.io/editor/)

**Browser console errors:**
- Check network tab for CDN library loading issues
- Verify Vega-Lite spec schema version matches (v5)

**Code block shown as plain text:**
- Make sure you're using ````{vega-lite}` not ````{json}` or ````json`

4.3 KiB Raw Blame History