Configuration

All site configuration lives in config.toml at the project root.

Any option documented as a list of strings also accepts a single string, which is read as a one-item list: sections = "posts" means sections = ["posts"]. An empty string, such as exclude = "${SITEMAP_EXCLUDE:-}" with the variable unset, counts as not set and keeps the default. A value that is neither a string nor a list (fields = true) is ignored with a warning.

Unknown top-level keys are reported instead of silently ignored. A typo'd [markdonw] or titel = "…" would otherwise disable a feature with no feedback. Hwaro warns with a suggestion when one is close to a real key:

Unknown key 'markdonw' in config.toml — hwaro does not read it. Did you mean 'markdown'?

The check covers top-level keys only: a misspelled key nested inside a section ([markdown] emoij = true) is not reported, so double-check nested keys against the tables below. A known section written in the wrong shape, such as highlight = false instead of a [highlight] table or taxonomies = ["tags"] instead of [[taxonomies]] entries, is ignored with a warning as well. sitemap = true is the one short form still accepted: it means [sitemap] enabled = true.

Site Settings

title = "My Site"
description = "Site description for SEO"
base_url = "https://example.com"

Environment Variables

You can reference environment variables in config.toml. Values are substituted before TOML parsing.

base_url = "${SITE_URL}"
title = "$SITE_TITLE"
description = "${SITE_DESC:-My awesome site}"

Missing variables without defaults are left as-is and produce a build warning. See Environment Variables for template usage.

Build Options

[build]
output_dir = "public"
drafts = false
parallel = true
cache = false
hooks.pre = ["npm install", "npx tsc"]
hooks.post = ["npm run minify"]

output_dir, drafts, parallel and cache each back a hwaro build flag, and the flag wins:

command-line flag  >  config.toml  >  built-in default

So hwaro build -o dist overrides output_dir in config, and hwaro build --drafts still includes drafts when drafts = false. The reverse does not exist: there is no --no-drafts or --no-cache to turn a config value back off, so set those keys only when you want them on for every build. --no-parallel is the one exception, and it overrides parallel = true.

drafts, parallel and cache apply to hwaro serve as well. output_dir does not: serve always builds into its own .hwaro/serve/ and leaves output_dir untouched (see the serve command). hwaro deploy does follow output_dir: when [deployment] source_dir is not set, it deploys output_dir rather than assuming public.

output_dir may be relative to the project or absolute. A relative path that escapes the project (../out) or an empty value is ignored with a warning, and the default public is used instead.

See Build Hooks for error handling and use cases.

Markdown

[markdown]
safe = false
lazy_loading = false
emoji = false
footnotes = true
task_lists = true
definition_lists = true
mermaid = false
math = false
math_engine = "katex"

See Markdown Extensions for syntax details and examples.

Content

[content]
summary_length = 70
summary_ellipsis = "…"
backlinks = false

See Content Summary for how page.summary is chosen. [content.files], [content.new], [[content.generate]] and [[content.schema]] are documented in the feature reference below.

Permalinks

Rewrite content directory paths to custom URL paths. Useful for site restructuring without breaking links.

[permalinks]
"old/posts" = "posts"
"2023/drafts" = "archive/2023"

Rules are evaluated in declaration order and the first source that matches the page's directory (exactly or as a parent prefix) wins. Later rules are never consulted for that page. Declare specific prefixes before broad ones ("posts/tech" before "posts"), or the broad rule shadows the specific one. This applies to token patterns too, and especially to the "" catch-all: put it last, after every other rule.

Token patterns

A target containing :token segments is a Hugo-style pattern that rebuilds the whole URL instead of remapping the directory:

[permalinks]
"posts" = "/:year/:month/:day/:slug/"

With content/posts/hello.md dated 2026-03-05, the page is published at /2026/03/05/hello/.

Notes:

• Tokens must be whole path segments; unknown tokens fail the config load.
• Patterns apply to leaf pages only. Section _index and bundle index pages skip pattern rules (they keep their directory URL, or a later plain remap rule).
• A page without a date that matches a pattern using :year/:month/:day fails the build. Add a date, set an explicit path in front matter, or drop the date tokens. Pages that never publish are exempt: drafts (without --drafts), expired/future-dated pages, and headless render: false pages don't block the build.
• An explicit path in front matter always wins over any permalink rule.
• An empty source key ("" or "/") makes a pattern rule a catch-all for every page. Declare it last, since first-match ordering means it would shadow any rule after it.
• For non-default languages the /lang/ prefix comes first: /ko/2026/03/05/hello/.

Links

Control how unresolved @/path.md internal links are treated during the build.

[links]
broken_internal = "error"
broken_anchors = "warn"

See Internal Links for the @/ link syntax and the --cache caveat in strict mode.

The anchor check reads each target page's output file after the render phase, so on --cache and serve rebuilds a target that was not re-rendered is checked as last written (no false positives). Only links in pages rendered in that pass are checked; run a cold build in CI for a complete check.

Taxonomies

[[taxonomies]]
name = "tags"
feed = true
paginate_by = 10

[[taxonomies]]
name = "categories"
feed = true

Term feeds stay reverse-chronological regardless of sort_by. See Taxonomies for the full sorting rules.

Menus

Named navigation menus, rendered in templates via site.menus / get_menu().

[[menus.main]]
name = "Posts"
url = "/posts/"
weight = 1

[[menus.main]]
name = "About"
url = "/about/"
weight = 2

Pages/sections can also join a menu from their own front matter (menus = ["main"]) without touching this file. A [languages.<code>] block with no menus table inherits this global set; declaring [[languages.<code>.menus.<name>]] replaces it for that language. See Menus for the full reference (hierarchy, per-language behavior, active_path styling).

To fill a menu from the top-level sections automatically (Hugo's sectionPagesMenu), name it under [menus]:

[menus]
auto_sections = "main"

Static Files

Everything under static/ is copied verbatim into the site root, preserving its directory structure, so static/css/app.css is served at /css/app.css. Hidden entries are included too, so static/.well-known/security.txt is published at /.well-known/security.txt. By default Hwaro filters out common OS, editor, and VCS cruft so it never ships to production.

[static]
use_default_excludes = true              # filter built-in cruft (default)
exclude = ["*.bak", "drafts/**"]         # extra patterns to skip

The built-in denylist only removes cruft. Legitimate dot-paths such as .well-known/ and .domains are never filtered and are always published, identically for cold and --cache/incremental builds. Set use_default_excludes = false to disable the built-in filtering entirely.

Development Server

Options for hwaro serve only. They never affect hwaro build output.

[serve]
fast = true                          # always serve in fast dev mode

[serve.headers]
X-Frame-Options = "SAMEORIGIN"
Cache-Control = "no-store"

See the serve command for the matching CLI flags.

Feature Configuration Reference

Each feature has its own documentation with full configuration details. Below is a quick reference of all config.toml sections.

Plugins

[plugins]
processors = ["markdown"]

Full Example

A complete config.toml with all core sections. Copy and adjust to your needs.

title = "My Blog"
description = "A blog about programming"
base_url = "https://myblog.com"
default_language = "en"

[build]
output_dir = "public"
drafts = false
parallel = true
cache = false
hooks.pre = ["npm ci"]
hooks.post = ["npm run optimize"]

[markdown]
safe = false
lazy_loading = true
emoji = false
footnotes = true
task_lists = true

[permalinks]
"old/posts" = "posts"
"posts" = "/:year/:month/:day/:slug/"

[plugins]
processors = ["markdown"]

[[taxonomies]]
name = "tags"
feed = true

[[taxonomies]]
name = "categories"

[[menus.main]]
name = "Posts"
url = "/posts/"

# Feature sections — see Feature Configuration Reference above
# [feeds], [sitemap], [robots], [og], [search], [highlight],
# [pagination], [auto_includes], [assets], [sass], [image_processing],
# [series], [related], [git], [llms], [pwa], [amp], [deployment], etc.

See Also

• CLI — Command-line options that override config
• Environment-Specific Config — Per-environment overrides (config.production.toml)