Examples
EN

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, reading time, and older/newer post navigation
docs Documentation with sidebar and prev/next page navigation
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.

The scaffolds also carry a quiet modern layer: a sticky glass header, native cross-document view transitions between pages, and (on blog posts and book pages) a CSS-only reading-progress thread. All of it degrades gracefully on older browsers and every animation respects prefers-reduced-motion.

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.

Optional: Build with an AI Agent

If you work with Claude Code, Cursor, Codex, or another skill-aware agent, Hwaro ships two Agent Skills that teach it how to drive the project you just created:

Skill What it does
hwaro Runs the CLI properly — init, new, serve, build, doctor, and the content tools — using the --json output contract and HWARO_E_* exit codes instead of guessing from text.
hwaro-design Designs and rethemes the site inside Hwaro's Crinja templates and light-dark() design tokens, under an anti-slop discipline that avoids generic AI-looking layouts.

Install both with one command:

npx skills add hahwul/hwaro

Then ask the agent something like "add a projects section to this Hwaro site" or "retheme this blog to a warm dark palette" — it loads the matching skill on its own. See Agent Skills for manual install paths and per-agent directories, and AGENTS.md to record project-specific conventions the agent should follow first.

Next Steps