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
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 scaffold
simple — Landing pages, small sites
bare scaffold
bare — Minimal structure, semantic HTML only
blog scaffold
blog — Posts with tags and categories
blog-dark scaffold
blog-dark — Blog, dark theme
docs scaffold
docs — Documentation with sidebar
docs-dark scaffold
docs-dark — Documentation, dark theme
book scaffold
book — Book with chapters
book-dark scaffold
book-dark — Book, dark theme

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

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