mirror of
https://github.com/olehomelchenko/olehomelchenko.com.git
synced 2026-02-05 02:54:37 +00:00
133 lines
2.9 KiB
Markdown
133 lines
2.9 KiB
Markdown
# Quick Start Guide
|
|
|
|
## ✅ Setup is Complete!
|
|
|
|
The Quarto site infrastructure is ready. Here's how to work with it:
|
|
|
|
## 🚀 Preview the Site
|
|
|
|
```bash
|
|
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:**
|
|
```bash
|
|
mkdir posts/your-post-slug
|
|
```
|
|
|
|
2. **Create `posts/your-post-slug/index.qmd`:**
|
|
```yaml
|
|
---
|
|
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!):
|
|
```bash
|
|
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):**
|
|
```markdown
|
|
{{</* vega-lite id="chart1" */>}}
|
|
{vega spec}
|
|
{{</* /vega-lite */>}}
|
|
```
|
|
|
|
**Quarto with Lua filter (NEW):**
|
|
````markdown
|
|
```{vega-lite}
|
|
{vega spec}
|
|
```
|
|
````
|
|
|
|
**With options:**
|
|
````markdown
|
|
```{vega-lite}
|
|
#| echo: false
|
|
#| code-fold: true
|
|
{vega spec}
|
|
```
|
|
````
|
|
|
|
See **`VEGA-LITE-SETUP.md`** for complete documentation and examples.
|
|
|
|
## 🔧 Common Commands
|
|
|
|
```bash
|
|
# 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.
|