README
¶
gohan
A simple, fast static site generator written in Go — featuring incremental builds, syntax highlighting, Mermaid diagrams, and a live-reload dev server.
日本語版: README.ja.md
This logo was created by gopherize.me.
Features
- Incremental builds — Regenerate only changed files, minimising build time
- Markdown + Front Matter — GitHub Flavored Markdown with YAML metadata
- Syntax highlighting — Code blocks styled with chroma
- Mermaid diagrams — Fenced
mermaidblocks render as interactive diagrams - Taxonomy — Tag and category pages generated automatically
- Atom feed & sitemap —
atom.xmlandsitemap.xmlgenerated automatically - Live-reload dev server —
gohan servewatches files and reloads the browser - Customisable themes — Full control via Go
html/template - Plugin system — Built-in plugins enabled per-project via
config.yaml(no Go code required) - i18n — Multi-locale content with per-article translation links and
hreflangsupport - OGP image generation — Build-time
1200×630Open Graph images, one per article - Pagination — Configurable
per_pagewith automatic next/previous page links - GitHub source link — Per-article link to the source file on GitHub for easy editing
- Related articles — Automatic same-category article recommendations on article pages
Installation
go install github.com/bmf-san/gohan/cmd/gohan@latest
Or build from source:
git clone https://github.com/bmf-san/gohan.git
cd gohan
make install
Pre-built binaries are available on GitHub Releases.
Quick Start
# 1. Create a project directory
mkdir myblog && cd myblog
# 2. Add config.yaml (see docs/guide/configuration.md for all options)
cat > config.yaml << 'EOF'
site:
title: My Blog
base_url: https://example.com
language: en
build:
content_dir: content
output_dir: public
theme:
name: default
EOF
# 3. Create your first article
gohan new --title="Hello, World!" hello-world
# 4. Build the site
gohan build
# 5. Preview locally with live reload
gohan serve # open http://127.0.0.1:1313
User Guide
| Guide | Description |
|---|---|
| Getting Started | Installation, first site, build & preview |
| Configuration | All config.yaml fields and Front Matter |
| Templates | Theme templates, variables, built-in functions |
| Taxonomy | Tags, categories, and archive pages |
| CLI Reference | All commands and flags |
Feature Documentation
| Feature | Description |
|---|---|
| i18n | Multi-locale content with translation links and hreflang |
| OGP Image Generation | Build-time Open Graph images per article |
| Pagination | Configurable per_page and page navigation |
| GitHub Source Link | Per-article link to the source file on GitHub |
| Plugin System | Built-in plugins (amazon_books, …) via config.yaml |
| Related Articles | Same-category article recommendations on article pages |
Design
For architecture and design decisions see docs/DESIGN_DOC.md.
Sites Built with gohan
| Site | Description |
|---|---|
| bmf-tech.com (source) | Personal tech blog — i18n (EN/JA), 700+ articles, Cloudflare Pages |
Contributing
See CONTRIBUTING.md for development setup and contribution guidelines.
Sponsor
If you'd like to support my work, please consider sponsoring me!
Or simply giving ⭐ on GitHub is greatly appreciated—it keeps me motivated to maintain and improve the project! :D
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
gohan
command
|
|
|
internal
|
|
|
config
Package config loads and validates gohan configuration from YAML files.
|
Package config loads and validates gohan configuration from YAML files. |
|
diff
Package diff detects changed files between builds using Git or file hash comparison.
|
Package diff detects changed files between builds using Git or file hash comparison. |
|
generator
Package generator writes rendered HTML, assets, sitemaps, and feeds to the output directory.
|
Package generator writes rendered HTML, assets, sitemaps, and feeds to the output directory. |
|
highlight
Package highlight provides chroma-based syntax highlighting for fenced code blocks in goldmark-rendered Markdown.
|
Package highlight provides chroma-based syntax highlighting for fenced code blocks in goldmark-rendered Markdown. |
|
mermaid
Package mermaid provides a goldmark extension that transforms fenced code blocks tagged with "mermaid" into browser-renderable <div class="mermaid"> elements for client-side rendering via the Mermaid.js CDN.
|
Package mermaid provides a goldmark extension that transforms fenced code blocks tagged with "mermaid" into browser-renderable <div class="mermaid"> elements for client-side rendering via the Mermaid.js CDN. |
|
parser
Package parser parses Markdown content and YAML Front Matter into Article structs.
|
Package parser parses Markdown content and YAML Front Matter into Article structs. |
|
plugin
Package plugin defines the gohan plugin interface and built-in plugin registry.
|
Package plugin defines the gohan plugin interface and built-in plugin registry. |
|
plugin/amazonbooks
Package amazonbooks is a gohan built-in plugin that generates Amazon book cards for article templates.
|
Package amazonbooks is a gohan built-in plugin that generates Amazon book cards for article templates. |
|
plugin/bookshelf
Package bookshelf is a gohan built-in SitePlugin that generates a bookshelf page by aggregating book entries from every article's front-matter.
|
Package bookshelf is a gohan built-in SitePlugin that generates a bookshelf page by aggregating book entries from every article's front-matter. |
|
processor
Package processor builds dependency graphs and processes articles for output.
|
Package processor builds dependency graphs and processes articles for output. |
|
server
Package server implements the local development HTTP server with live reload.
|
Package server implements the local development HTTP server with live reload. |
|
template
Package template loads Go html/template files and renders pages with site data.
|
Package template loads Go html/template files and renders pages with site data. |
Click to show internal directories.
Click to hide internal directories.