olehomelchenko.com/VEGA-LITE-SETUP.md

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

1. vega-lite.lua - Custom Lua filter that processes Vega-Lite code blocks
2. _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}
{your vega spec}
```

Supported options:

• echo=false - Hide the code, show only the visualization
• echo=true - Show code (default)
• code-fold=true - Make code collapsible and collapsed (default)
• code-fold=show - Make code collapsible but expanded by default
• code-fold=false - Show code expanded, not collapsible

Default behavior: Code is shown in a collapsed, expandable section. Click to view the code.

🔧 How the Filter Works

The vega-lite.lua filter:

1. Detects code blocks with class vega-lite
2. Includes Vega libraries (Vega, Vega-Lite, Vega-Embed) from CDN
3. Renders the specification using vegaEmbed() JavaScript
4. 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

1. Find Hugo shortcode:

   {{</* vega-lite id="..." */>}}
   

2. Copy the JSON spec (everything between the shortcode tags)

3. Replace with code fence:

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

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

🧪 Testing

After adding a Vega-Lite visualization:

1. Build: quarto render
2. Preview: quarto preview
3. 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`