Configuration

Taxus uses a site.toml configuration file to define site settings and build options.

Configuration File

Create a site.toml file in your project root:

[site]
name = "My Site"
base_url = "https://example.com"
description = "A description of my site"
author = "Your Name"

[build]
content_dir = "content"
output_dir = "dist"
static_dir = "static"
styles_dir = "styles"
templates_dir = "templates"

[feed]
rss_enabled = true
atom_enabled = false
limit = 20
full_content = false

Configuration Sections

`[site]` Section

Site metadata and information.

Field	Type	Required	Description
`name`	string	Yes	Site name/title
`base_url`	string	Yes	Base URL for the site (used for absolute URLs)
`description`	string	No	Site description for SEO
`author`	string	No	Site author name

`[build]` Section

Build configuration options. All fields have defaults.

Field	Type	Default	Description
`content_dir`	string	`"content"`	Directory containing Markdown content
`output_dir`	string	`"dist"`	Output directory for generated files
`static_dir`	string	`"static"`	Directory containing static assets
`styles_dir`	string	`"styles"`	Directory containing SCSS stylesheets
`templates_dir`	string	`"templates"`	Directory containing HTML templates
`islands`	bool	`true`	Compile and embed the WASM hydration client. `taxus init --no-islands` writes `false`; the build then skips `dist/wasm/`
`search`	bool	`true`	Build `search_index.bin`. Set `false` on sites with no search box

`[feed]` Section

RSS/Atom feed configuration for content syndication.

Field	Type	Default	Description
`rss_enabled`	bool	`true`	Enable RSS 2.0 feed generation
`atom_enabled`	bool	`false`	Enable Atom feed generation
`limit`	number	no limit	Maximum entries in feed. Unset means no limit; `0` is rejected (to disable feeds, use `rss_enabled` / `atom_enabled`)
`full_content`	bool	`false`	Include full content vs summary
`title`	string	`None`	Custom feed title (defaults to site name)
`rss_path`	string	`None`	RSS feed output path (default: `feed.xml`)
`atom_path`	string	`None`	Atom feed output path (default: `feed.atom`)
`sections`	array	`[]`	Sections whose pages the feeds syndicate, e.g. `["blog"]`; empty means every section

`[highlight]` Section

Syntax highlighting configuration for code blocks.

Field	Type	Default	Description
`enabled`	bool	`true`	Enable tree-sitter syntax highlighting
`class_prefix`	string	`"hl-"`	CSS class prefix for highlight spans

See Syntax Highlighting for details on styling and supported languages.

`[images]` Section

Responsive image processing configuration for hero images.

Field	Type	Default	Description
`widths`	array	`[400, 800, 1200]`	Responsive breakpoint widths in pixels
`quality`	number	`80`	Output quality (1–100). Applies to `"jpeg"` and `"webp"` only; `"png"` ignores it
`format`	string	`"webp"`	Output format: `"webp"`, `"jpeg"` (alias `"jpg"`), or `"png"`
`output_dir`	string	`"images"`	Subdirectory within `dist/` for processed images

See Images for details on hero images and template usage.

`[markdown]` Section

Markdown rendering options.

Field	Type	Default	Description
`insert_anchor_links`	bool	`false`	Insert a visible anchor link (`#`) into each heading for deep-linking

Minimal Configuration

The minimal required configuration:

[site]
name = "My Site"
base_url = "https://example.com"

All other sections ([build], [feed], [highlight], [images], [markdown]) use their default values.

Full Configuration Example

[site]
name = "My Blog"
base_url = "https://example.com"
description = "A blog about Rust and web development"
author = "Jane Doe"

[build]
content_dir = "content"
output_dir = "dist"
static_dir = "static"
styles_dir = "styles"
templates_dir = "templates"

[feed]
rss_enabled = true
atom_enabled = true
limit = 20
full_content = false
title = "My Blog Feed"
rss_path = "feed.xml"
atom_path = "feed.atom"

[highlight]
enabled = true
class_prefix = "hl-"

[images]
widths = [400, 800, 1200]
quality = 80
format = "webp"
output_dir = "images"

[markdown]
insert_anchor_links = false

Validation

Configuration is validated when loaded:

site.name must not be empty
site.base_url must not be empty and must start with http:// or https://
images.quality must be between 1 and 100
images.format must be "webp", "jpeg", "jpg", or "png"
images.widths must list at least one breakpoint
[feed] limit must not be 0 (unset means no limit)

Unknown keys are rejected in every section ([site], [build], [feed], [highlight], [images], [markdown]): a typo like ouput_dir fails the build naming the unknown field, rather than silently leaving the real key at its default.

Feed URLs

After generation, feeds are available at:

RSS: https://example.com/feed.xml (or custom rss_path)
Atom: https://example.com/feed.atom (or custom atom_path)

Taxus Documentation