First Site
Create your first Hwaro site in 5 minutes.
1. Create Project
hwaro init my-site --scaffold blog
cd my-site
Built-in scaffolds:
| Scaffold | Description |
|---|---|
simple |
Landing pages, small sites (default) |
bare |
Minimal structure with semantic HTML only |
blog |
Posts with tags and categories |
blog-dark |
Blog with dark theme |
docs |
Documentation with sidebar |
docs-dark |
Documentation with dark theme |
book |
Book with chapters, prev/next navigation, keyboard shortcuts |
book-dark |
Book with dark theme |

simple — Landing pages, small sites
bare — Minimal structure, semantic HTML only
blog — Posts with tags and categories
blog-dark — Blog, dark theme
docs — Documentation with sidebar
docs-dark — Documentation, dark theme
book — Book with chapters
book-dark — Book, dark themeTip: Looking for a more complete starting point? Check out the Hwaro Examples for ready-made boilerplates you can use right away.
2. Start Development Server
hwaro serve
Open http://localhost:3000. Changes reload automatically.
3. Project Structure
my-site/
├── config.toml # Site configuration
├── content/ # Markdown content
│ ├── index.md # Homepage
│ └── blog/ # Blog section
│ ├── _index.md
│ └── hello.md
├── templates/ # Jinja2 templates
├── static/ # Static files (CSS, JS, images)
└── public/ # Generated output
4. Edit Configuration
Open config.toml:
title = "My Site"
description = "A site built with Hwaro"
base_url = "https://example.com"
5. Create a Page
hwaro new content/about.md
Edit content/about.md:
+++
title = "About"
+++
Welcome to my site!
Visit http://localhost:3000/about/.
6. Create a Section
Sections group related content. Create a blog section:
mkdir -p content/blog
Create content/blog/_index.md:
+++
title = "Blog"
sort_by = "date"
+++
My blog posts.
Create content/blog/first-post.md:
+++
title = "My First Post"
date = "2024-01-15"
tags = ["hello"]
+++
Hello, world!
Visit http://localhost:3000/blog/.
7. Build for Production
hwaro build
Deploy the public/ directory to any static host. See Deploy to GitHub Pages for a quick setup.
Next Steps
- CLI Commands — All available commands
- Configuration — Full config reference
- Writing Content — Pages, sections, taxonomies
- Deploy — Hosting and deployment guides