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:**
   ```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.