CLI Reference
Commands
| Command | Description |
|---|---|
gohan build |
Build the site (incremental by default) |
gohan build --full |
Force a full rebuild |
gohan build --dry-run |
Simulate a build without writing files |
gohan build --draft |
Include draft articles (draft: true) in the build |
gohan build --future |
Include articles whose date is in the future |
gohan build --stats |
Print per-phase timing and counts after the build |
gohan build --explain |
Print which files triggered a rebuild and why |
gohan init [--force] [<dir>] |
Scaffold a new gohan project (config + content + archetypes) |
gohan new [--type=post] [--title=<t>] <slug> |
Create a new post skeleton |
gohan new --type=<section> --archetype=<name> <slug> |
Create content for a custom section using an archetype template |
gohan new --type=page [--title=<t>] <slug> |
Create a new page skeleton |
gohan check |
Validate content for duplicate slugs, missing front matter, and orphan translation keys |
gohan serve |
Start the live-reload development server |
gohan version |
Print version information |
gohan build
Builds the site from content/ into the configured output directory.
By default, only files that have changed since the last build are regenerated (incremental build). Use --full to rebuild everything.
Flags
| Flag | Description |
|---|---|
--full |
Skip diff detection and regenerate all pages |
--dry-run |
Print what would be generated without writing any files |
--draft |
Include articles with draft: true in their Front Matter. By default drafts are excluded. |
--future |
Include articles whose date is later than the current time. By default future-dated articles are excluded, allowing them to be "scheduled" by setting a future date. |
--stats |
Print a per-phase timing report (parse / diff / process / plugins / render / feeds / manifest) and total wall-clock time. |
--explain |
Print which content files triggered the rebuild. For a full rebuild it also prints the reason (e.g. --full flag, config hash change, missing manifest). |
gohan init
Scaffolds a new gohan project under the given directory (or the current directory if omitted).
Usage
gohan init [--force] [<dir>]
Generates a minimal config.yaml, the standard content/ and archetypes/ folders, and a starter README.md. The command refuses to write into a non-empty directory unless --force is given. Existing files are never overwritten — --force only allows writing alongside them.
Flags
| Flag | Description |
|---|---|
--force |
Allow scaffolding into a non-empty directory. Existing files are preserved. |
gohan new
Creates a new content skeleton with pre-filled Front Matter.
Flags
| Flag | Description |
|---|---|
--type |
Content section: post (default → content/posts/), page (→ content/pages/), or any other name (→ content/<name>/). |
--archetype |
Archetype template name under archetypes/. Defaults to the value of --type. |
--title |
Article title (defaults to slug converted to title case) |
Usage
| Usage | Description |
|---|---|
gohan new [--type=post] [--title=<t>] <slug> |
Create content/posts/<slug>.md |
gohan new --type=page [--title=<t>] <slug> |
Create content/pages/<slug>.md |
gohan new --type=tutorial intro |
Create content/tutorial/intro.md using archetypes/tutorial.md if present |
gohan new --archetype=news <slug> |
Create content/posts/<slug>.md using archetypes/news.md |
Archetypes
When archetypes/<name>.md exists in the project root, gohan new renders it through Go's text/template package with the following variables:
| Variable | Description |
|---|---|
{{ .Title }} |
Resolved title (from --title or slug) |
{{ .Date }} |
Today's date in YYYY-MM-DD |
{{ .Slug }} |
The slug argument |
{{ .Type }} |
The --type value |
If no archetype file exists, built-in templates are used for post and page. Any other --type value requires a matching archetype file.
If --title is omitted, gohan derives a title from the slug (e.g. my-post → My Post).
gohan check
Validates the content directory without performing a build. Reports:
missing-title— front matter has notitlemissing-date— front matter has nodateduplicate-slug— two articles in the same directory resolve to the same slugorphan-translation-key— atranslation_keyis referenced by only one article (no actual translation pair)
Flags
| Flag | Description |
|---|---|
--config |
Path to the config file (defaults to config.yaml) |
Exits with code 1 if any issues are found. Intended for use in CI before running gohan build.
gohan serve
Starts a local HTTP development server with live reload.
- Default address:
http://127.0.0.1:1313 - Watches
content/,themes/, andassets/for changes - Automatically rebuilds and reloads the browser on file changes
- CSS-only hot swap: when every changed file in a debounce window is a
.cssfile, stylesheets are reloaded in place via a cache-busting query parameter instead of triggering a full page reload, preserving scroll position and form state.
gohan version
Prints the version, commit hash, and build date of the installed binary.