feat: set up migration to quarto

2026-02-05 02:54:37 +00:00 · 2026-01-08 03:57:13 +02:00
parent 8c127289c7
commit a907728269
24 changed files with 1151 additions and 0 deletions
--- a/MIGRATION-README.md
+++ b/MIGRATION-README.md
@@ -0,0 +1,250 @@
+# Hugo to Quarto Migration Guide
+
+## ✅ Migration Status: Infrastructure Complete
+
+The Quarto site infrastructure is now fully set up! The site builds successfully and is ready for content migration.
+
+## 🏗️ What's Been Created
+
+### Configuration
+- `_quarto.yml` - Main site configuration with navbar, footer, analytics, **Vega-Lite filter**
+- `vega-lite.lua` - **Lua filter for Vega-Lite support** (Quarto doesn't have native support)
+- `styles.css` - Minimal custom styling (Vega chart centering)
+- `_includes/analytics.html` - Plausible + Matomo analytics
+- `_redirects` - URL redirects for old `/en/*` paths
+- `.gitignore` - Updated with Quarto-specific entries
+
+### Directory Structure
+```
+├── posts/                    # Blog posts (3 sample placeholders)
+├── til/                      # TILs (2 sample placeholders)
+├── portfolio/                # Portfolio listing page
+├── projects/                 # Projects section (1 sample project)
+├── about/                    # About page template
+└── index.qmd                 # Homepage
+```
+
+### Sample Content (Placeholders)
+- `posts/sample-ukrainian-post/` - Example Ukrainian post structure
+- `posts/sample-english-post/` - Example English post structure
+- `posts/sample-visualization-post/` - Example with Vega-Lite chart
+- `til/sample-til-ukrainian.qmd` - Example Ukrainian TIL
+- `til/sample-til-english.qmd` - Example English TIL
+- `projects/sample-project-1/` - Example full project page
+
+## 📝 Manual Migration Steps
+
+### 1. Migrate Blog Posts (8 posts)
+
+For each Hugo post in `content/posts/` and `content/en/posts/`:
+
+1. **Create directory:** `posts/{post-slug}/`
+2. **Convert file:** Copy `.md` → `index.qmd` in the new directory
+3. **Update frontmatter:**
+   ```yaml
+   ---
+   title: "Your Title"
+   date: "YYYY-MM-DD"
+   lang: uk  # or 'en' for English posts
+   categories:
+     - dataviz
+     - showcase  # Add this for portfolio items!
+   description: "Brief description"
+   ---
+   ```
+4. **Convert Vega-Lite shortcodes:**
+   - Remove: `{{</* vega-lite id="..." */>}}...{{</* /vega-lite */>}}`
+   - Replace with:
+   ````markdown
+   ```{vega-lite}
+   {your vega spec here}
+   ```
+   ````
+   - See `VEGA-LITE-SETUP.md` for detailed instructions
+
+**Posts to migrate:**
+- `content/posts/dataviz-blogs.md` → `posts/dataviz-blogs/index.qmd`
+- `content/posts/dataviz-books-ua.md` → `posts/dataviz-books-ua/index.qmd`
+- `content/posts/entso-e-ukraine-energy-transfer-viz.md` → `posts/entso-e-ukraine-energy-transfer-viz/index.qmd`
+- `content/posts/forbes-50-foundations.md` → `posts/forbes-50-foundations/index.qmd` **(add 'showcase' category)**
+- `content/posts/my-first-post.md` → `posts/my-first-post/index.qmd`
+- `content/posts/vega-altair-hugo-shortcodes.md` → `posts/vega-altair-hugo-shortcodes/index.qmd` **(add 'showcase' category)**
+- `content/en/posts/bar-charts-makeover.md` → `posts/bar-charts-makeover/index.qmd` **(add 'showcase' category, lang: en)**
+
+### 2. Migrate TILs (2 posts)
+
+For each Hugo TIL in `content/til/`:
+
+1. **Convert file:** Copy `.md` → `.qmd` directly in `til/` folder
+2. **Update frontmatter:**
+   ```yaml
+   ---
+   title: "Your Title"
+   date: "YYYY-MM-DD"
+   lang: uk
+   categories:
+     - tools
+   ---
+   ```
+
+**TILs to migrate:**
+- `content/til/inspired-by-blogs.md` → `til/inspired-by-blogs.qmd`
+- `content/til/obsidian-paperless.md` → `til/obsidian-paperless.qmd`
+
+### 3. Posts/TILs Auto-Discovery
+
+✅ **Good news!** The listing pages automatically discover new posts and TILs:
+
+- **Posts:** Any directory with `index.qmd` in `posts/` appears automatically
+- **TILs:** Any `.qmd` file in `til/` appears automatically
+- **No manual updates needed!** Just add your files and they'll show up
+
+### 4. Update Portfolio Page
+
+The portfolio page needs manual updates. Edit `portfolio/index.qmd` and add your showcase posts:
+
+```markdown
+::: {.g-col-12 .g-col-md-6}
+### [Forbes Top-50 Foundations](../posts/forbes-50-foundations/)
+Interactive visualization of Ukraine's top charitable foundations
+:::
+
+::: {.g-col-12 .g-col-md-6}
+### [Bar Charts Makeover](../posts/bar-charts-makeover/)
+Seven ways to visualize year-over-year growth
+:::
+```
+
+### 5. Delete Sample Placeholders
+
+After migrating and updating listings, delete these placeholder files:
+```bash
+rm -rf posts/sample-*
+rm til/sample-*
+rm -rf projects/sample-project-1
+```
+
+### 6. Customize About Page
+
+Edit `about/index.qmd` and replace template content with:
+- Your bio
+- Skills and expertise
+- Contact information
+- Links to social profiles
+
+### 7. Add Real Projects
+
+Option A: Full project page
+```bash
+mkdir projects/your-project-name
+# Create projects/your-project-name/index.qmd
+```
+
+Option B: Just list in `projects/index.qmd`
+
+## 🔧 Key Technical Details
+
+### Language Tags
+Use `lang: uk` or `lang: en` in frontmatter to tag content language. This allows filtering by language if needed.
+
+### Portfolio Items
+Add `showcase` to the categories list for any post you want in your portfolio:
+```yaml
+categories:
+  - dataviz
+  - showcase  # This makes it appear in portfolio
+```
+
+### Vega-Lite Visualizations
+Enabled via `vega-lite.lua` filter (already configured). Use:
+````markdown
+```{vega-lite}
+{
+  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
+  "mark": "bar",
+  ...
+}
+```
+````
+
+Optional attributes:
+- `#| echo: false` - Hide code, show only visualization
+- `#| code-fold: true` - Make code collapsible
+
+See `VEGA-LITE-SETUP.md` for complete documentation.
+
+## 🚀 Building & Previewing
+
+### Local Preview
+```bash
+quarto preview
+```
+Opens at `http://localhost:4848`
+
+### Build Site
+```bash
+quarto render
+```
+Output goes to `_site/`
+
+### Check for Errors
+```bash
+quarto check
+```
+
+## 📂 What to Keep vs Delete
+
+### Keep (Quarto):
+- All `*.qmd` files
+- `_quarto.yml`
+- `styles.css`
+- `_includes/`
+- `_redirects`
+- `_site/` (build output)
+
+### Can Eventually Delete (Hugo):
+- `archetypes/`
+- `content/` (after migrating to `posts/` and `til/`)
+- `data/`
+- `i18n/`
+- `layouts/`
+- `public/`
+- `resources/`
+- `static/`
+- `templates/`
+- `themes/`
+- `hugo.yaml`
+
+**Don't delete Hugo files yet!** Wait until you've confirmed the Quarto migration is complete and deployed.
+
+## 🌐 Deployment
+
+1. Build: `quarto render`
+2. Deploy `_site/` directory to your hosting
+3. Ensure `_redirects` file is included for old URL support
+
+## 📌 Important Notes
+
+- **URL Preservation:** Old `/en/posts/*` URLs will redirect to `/posts/*` via `_redirects`
+- **Analytics:** Already integrated (Plausible + Matomo)
+- **No Language Duplication:** All posts in one location, tagged with `lang` field
+- **Sample Content:** Delete all `sample-*` files after migrating real content
+
+## ✨ Benefits You'll Gain
+
+1. ✅ Vega-Lite support via Lua filter (cleaner than Hugo shortcodes)
+2. ✅ Can add Python/R code that generates visualizations
+3. ✅ Observable JS for interactive dashboards
+4. ✅ Better data analysis workflows
+5. ✅ Single source of truth (no language directory duplication)
+6. ✅ Cleaner, more maintainable structure
+
+## 📚 Additional Documentation
+
+- **`VEGA-LITE-SETUP.md`** - Complete guide to Vega-Lite filter and usage
+- **`QUICK-START.md`** - How to use Quarto, add posts, common commands
+- **`MIGRATION-CHECKLIST.md`** - Checkbox list to track migration progress
+
+---
+
+**Ready to migrate!** Start with one post to test the workflow, then batch-migrate the rest.