Configuration

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

Site Settings

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

Key	Type	Description
title	string	Site title
description	string	Site description
base_url	string	Production URL (no trailing slash)

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}"

Syntax	Description
`${VAR}`	Substitute with env var value
`$VAR`	Same as above (bare form)
`${VAR:-default}`	Use `default` if `VAR` is unset or empty

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"]

Key	Type	Default	Description
output_dir	string	"public"	Output directory
drafts	bool	false	Include draft content
parallel	bool	true	Parallel processing
cache	bool	false	Enable build caching
hooks.pre	array	[]	Commands to run before build
hooks.post	array	[]	Commands to run after build

See Build Hooks for error handling and use cases.

Markdown

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

Key	Type	Default	Description
safe	bool	false	Strip raw HTML from markdown
lazy_loading	bool	false	Automatically add `loading="lazy"` to images
emoji	bool	false	Convert emoji shortcodes (e.g. `:smile:`) to emoji characters
footnotes	bool	true	Enable footnote syntax (`[^1]`)
task_lists	bool	true	Enable task list syntax (`- [ ]` / `- [x]`)
definition_lists	bool	true	Enable definition list syntax (`Term\n: Definition`)
mermaid	bool	false	Render ``mermaid` blocks as `<div class="mermaid">`
math	bool	false	Enable math syntax ( $...$ and `$$...$$`)
math_engine	string	"katex"	Math rendering engine (`"katex"` or `"mathjax"`)

See Markdown Extensions for syntax details and examples.

Permalinks

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

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

Source (Directory)	Target (URL Path)	Example Effect
`content/old/posts/a.md`	`posts/`	`/old/posts/a/` -> `/posts/a/`

Taxonomies

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

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

Key	Type	Default	Description
name	string	—	Taxonomy name (used in front matter)
feed	bool	false	Generate RSS feed for each term
sitemap	bool	true	Include taxonomy pages in sitemap
paginate	int	—	Pages per pagination page

Feature Configuration Reference

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

Config Section	Documentation	Description
`[feeds]`	SEO	RSS/Atom feed generation
`[sitemap]`	SEO	Sitemap XML generation
`[robots]`	SEO	Robots.txt generation
`[og]`	SEO	OpenGraph & Twitter Card meta tags
`[og.auto_image]`	Auto OG Images	Auto-generate OG preview images
`[search]`	Search	Client-side search index
`[highlight]`	Syntax Highlighting	Code syntax highlighting
`[pagination]`	Pagination	Section pagination
`[auto_includes]`	Auto Includes	Auto-include CSS/JS files
`[assets]`	Asset Pipeline	CSS/JS minification & fingerprinting
`[image_processing]`	Image Processing	Image resizing & LQIP
`[image_processing.lqip]`	Image Processing	Base64 blur-up placeholders
`[content.files]`	Content Files	Publish non-Markdown files
`[series]`	Series	Group posts into ordered series
`[related]`	Related Posts	Related content recommendations
`[llms]`	LLMs.txt	AI/LLM crawler instructions
`[pwa]`	PWA	Progressive Web App support
`[amp]`	AMP	Accelerated Mobile Pages
`[deployment]`	Deploy	Deploy targets configuration
`[doctor]`	Doctor	Suppress known diagnostic issues
`languages.*`	Multilingual	Multi-language support

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"

[plugins]
processors = ["markdown"]

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

[[taxonomies]]
name = "categories"

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