olehomelchenko.com/QUICK-START.md

Quick Start Guide

✅ Setup is Complete!

The Quarto site infrastructure is ready. Here's how to work with it:

🚀 Preview the Site

quarto preview

Opens at http://localhost:4848 with live reload.

🎨 Theme & Styling

• Theme: Cosmo (clean, minimal Bootstrap theme)
• Custom CSS: styles.css (minimal - just Vega chart centering)
• To change theme, edit _quarto.yml and try: cosmo, flatly, litera, minty, etc.

📝 Adding Your First Real Post

1. Create post directory:

   mkdir posts/your-post-slug
   

2. Create posts/your-post-slug/index.qmd:

   ---
   title: "Your Post Title"
   date: "2024-03-15"
   lang: uk  # or 'en'
   categories:
     - dataviz
     - showcase  # Include for portfolio items
   description: "Brief description"
   ---
   
   Your content here...
   

3. Preview changes (posts auto-discovered!):

   quarto preview
   

   ✅ Your new post will automatically appear in the listing - no manual updates needed!

📊 Using Vega-Lite Visualizations

Important: This project uses vega-lite.lua filter for Vega-Lite support.

Hugo shortcode (OLD):

{{</* vega-lite id="chart1" */>}}
{vega spec}
{{</* /vega-lite */>}}

Quarto with Lua filter (NEW):

```{vega-lite}
{vega spec}
```

With options:

```{vega-lite}
#| echo: false
#| code-fold: true
{vega spec}
```

See VEGA-LITE-SETUP.md for complete documentation and examples.

🔧 Common Commands

# Preview with live reload
quarto preview

# Build the site
quarto render

# Check for issues
quarto check

# Clean build cache
quarto clean

📂 Where Things Go

• Blog posts: posts/post-slug/index.qmd
• TILs: til/post-name.qmd
• Projects: projects/project-name/index.qmd (or just list in projects/index.qmd)
• About page: about/index.qmd
• Homepage: index.qmd

⚠️ Important Notes

1. Use lang: uk or lang: en (not language: - that's reserved by Quarto)
2. Update listing pages when you add real content (see MIGRATION-README.md)
3. Posts with showcase category automatically appear in portfolio
4. Delete sample files after migrating your real content

🆘 Troubleshooting

Error: "list needs to have at least one item"

• Update the listing contents: in the index page to reference actual files/directories

Vega chart not showing:

• Check the JSON is valid
• Ensure you're using ````{vega-lite}code fence (not{json}`)
• Check browser console for errors

Styles look wrong:

• Run quarto clean && quarto render to rebuild from scratch
• Check styles.css hasn't been corrupted

📚 Next Steps

1. Test by migrating one post from Hugo
2. Verify it displays correctly
3. Batch migrate the rest
4. Update all listing pages
5. Delete sample placeholders
6. Deploy!

See MIGRATION-README.md for detailed migration instructions.