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:
   ```yaml
   filters:
     - vega-lite.lua
   ```

## 🎨 How to Use Vega-Lite in Your Posts

### Basic Usage

````markdown
```{.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

````markdown
```{.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):**
```markdown
{{</* 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):**
````markdown
```{.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:**
   ```markdown
   {{</* vega-lite id="..." */>}}
   ```

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

3. **Replace with code fence:**
   ````markdown
   ```{.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

```yaml
---
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`