feat: set up migration to quarto

VEGA-LITE-SETUP.md

@@ -0,0 +1,181 @@
+# 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
+#| 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:
+
+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`