olehomelchenko.com/MIGRATION-README.md

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:

   ---
   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:

   ```{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:

   ---
   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:

::: {.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:

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

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:

categories:
  - dataviz
  - showcase  # This makes it appear in portfolio

Vega-Lite Visualizations

Enabled via vega-lite.lua filter (already configured). Use:

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

quarto preview

Opens at http://localhost:4848

Build Site

quarto render

Output goes to _site/

Check for Errors

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.