hahwul/hwaro

Hwaro (화로) is a lightweight and fast Static Site Generator(SSG) written in Crystal.

stars

1,449

commits

Crystal

primary language

Sep 8, 2026

updated

hwaro.hahwul.com

blog-engine

crystal

hwaro

jinja2

markdown

seo

ssg

static-site-generator

Browse cluster: AI agents and model context protocol →

README

A lightweight and fast static site generator written in Crystal.

Documentation • Installation • Github Action • Contributing • Changelog

Hwaro processes Markdown content with TOML, YAML, or JSON front matter and Jinja2-compatible templates (Crinja) to build high-performance static sites. It features parallel builds, incremental caching, and a built-in dev server with live reload.

Features

Content & Templating

Markdown with TOML/YAML/JSON front matter
Jinja2 templates (inheritance, includes, macros)
Markdown extensions: task lists, footnotes, definition lists, math (KaTeX/MathJax), Mermaid diagrams, emoji, etc
Built-in shortcodes (YouTube, Vimeo, Gist, Alert, Figure, Tweet, CodePen) and custom shortcode support
Build-time syntax highlighting (Tartrazine, hljs-compatible classes; optional client mode via Highlight.js)
Table of contents (TOC) generation
Reading time and word count
Content summaries via  marker
Non-markdown content file publishing

Content Management

Draft, scheduled, and expiring post support
URL aliases and redirects
Archetypes for content scaffolding templates
Data files (YAML, JSON, TOML) accessible in templates
Author data aggregation and management
Page weight and custom sorting (by date, weight, title)

Build & Performance

Multi-threaded parallel processing (Crystal execution contexts) — tune with CRYSTAL_WORKERS (defaults to the CPU count)
Incremental build caching
Streaming build mode with memory limits
Pre/post build hooks
Built-in Sass/SCSS compilation (pure Crystal, no external tools)
CSS/JS bundling, minification, and content-hash fingerprinting
Lazy loading images
Environment-specific config (config.production.toml, config.staging.toml, etc.)

SEO & Discovery

Auto-generated sitemap, robots.txt, RSS/Atom feeds
OpenGraph meta tags and auto-generated OG images (PNG)
Twitter Cards and JSON-LD structured data (Article, FAQ, HowTo, Organization, Person)
Canonical URLs and hreflang tags
llms.txt and AGENTS.md generation
Client-side search index (Fuse.js, ElasticLunr) with CJK tokenization

Site Features

Pagination, taxonomies (tags, categories, custom)
Content series and related posts
Breadcrumb navigation and previous/next page links
Multilingual (i18n) with per-language feeds and search
Image processing (resize, responsive images, LQIP blur-up placeholders, dominant color extraction) and auto-generated OG images
PWA support (manifest, service worker)
AMP page generation
Transparent sections for flexible content organization

Development & Deployment

Dev server with live reload and error overlay
Scaffolding with built-in themes (simple, bare, blog, docs, book) — auto light/dark with a built-in theme switcher
Deploy to multiple targets with dry-run support
Platform config generation (Netlify, Vercel, Cloudflare Pages, GitHub Pages, GitLab CI)
Import from WordPress, Jekyll, Hugo
Link checker, config doctor, and front matter format conversion

Installation

Homebrew

brew tap hahwul/hwaro
brew install hwaro

From source

# Clone the repository
git clone https://github.com/hahwul/hwaro.git
cd hwaro

# Install dependencies
shards install

# Build
# Parallelism comes from Crystal's execution contexts, sized in src/main.cr
# (same as the official binaries). Requires Crystal >= 1.21.
shards build --release --no-debug --production

For more installation options including Docker and pre-built binaries, see the Installation Guide.

Contributing

Hwaro is an open-source project made with ❤️. If you would like to contribute, please check CONTRIBUTING.md and submit a Pull Request.

Why "Hwaro"?

Hwaro (화로) is the Korean word for Furnace — the same name used in Minecraft's Korean localization. In the game, the Furnace is an essential tool that transforms raw materials into useful items. Hwaro aims to serve the same role for static sites: feed in your content, and it crafts a complete website.