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
- Project scaffolding —
gohan initbootstrapsconfig.yaml, content folders, and archetype templates - Content linter —
gohan checkvalidates duplicate slugs, missing front matter, and orphan translation keys - Archetype templates —
gohan new --archetype=<name>renders custom front-matter skeletons fromarchetypes/<name>.md - Markdown + Front Matter — GitHub Flavored Markdown with YAML metadata
- TOC / WordCount / ReadingTime — Auto-derived per article and exposed to templates
- Scheduled posts — Future-dated articles are skipped by default; opt in with
gohan build --future - Build observability —
--statsprints per-phase timing;--explainshows what triggered a rebuild - 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 (CSS-only changes hot-swap stylesheets without a full reload) - 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. Scaffold a new project (creates config.yaml, content/, archetypes/, README.md)
gohan init myblog && cd myblog
# 2. Create your first article (uses archetypes/post.md)
gohan new --title="Hello, World!" hello-world
# 3. Validate the content (optional but recommended in CI)
gohan check
# 4. Build the site
gohan build
# 5. Preview locally with live reload
gohan serve # open http://127.0.0.1:1313
See Configuration for all config.yaml options.
Documentation
Full documentation site: https://bmf-san.github.io/gohan/
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.