Examples

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
docs Documentation with sidebar
book Book with chapters, prev/next navigation, keyboard shortcuts

Every scaffold shares one design-token system built on CSS light-dark() pairs, so each site automatically follows the reader's OS color scheme — light for light, dark for dark, with no extra setup. The styled scaffolds also ship a theme switcher in the header: it cycles auto → light → dark, persists the choice in localStorage, and applies it before first paint so there is no flash. To force one scheme permanently (a dark-only site), add :root { color-scheme: dark; } at the end of the generated css/style.css.

simple scaffold
simple — Landing pages, small sites
 bare scaffold
bare — Minimal structure, semantic HTML only
 blog scaffold
blog — Posts with tags and categories
 docs scaffold
docs — Documentation with sidebar
 book scaffold
book — Book with chapters

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

Tip: run hwaro new with no arguments to open an interactive wizard that suggests a path and collects the title, description, tags, and more for you.

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