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.

[build] Section

Build configuration options. All fields have defaults.

flatten

Directories matching a flatten pattern organise files on disk without appearing in the site. A page in a flattened directory belongs to the nearest ancestor section that is not flattened:

[build]
flatten = ["blog/*"]

With this setting, content/blog/2026/2026-04-07-rust-fundamentals-comments.md is served at /blog/rust-fundamentals-comments/, and blog/2026 is not a section.

Pattern rules:

• A pattern is a directory path relative to content_dir, separated by /. Write / on Windows too; a \ in a pattern is read as /.
• It is matched against the directory name as it is on disk, before slugification, and the match is case-sensitive.
• * matches exactly one path segment. There is no **; write "blog/*/*" for year/month folders.
• A literal path such as "blog/drafts" is a valid pattern.
• The default, [], flattens nothing.

flatten needs taxus 1.4.0 or later. An older taxus stops with unknown field `flatten` instead of building the site with the wrong URLs, so pin your deploy to 1.4.0 or later before you move files into flattened directories.

The practical guide, with the rules for @/ links, co-located assets and duplicate URLs, is in Content: Organising files without changing URLs.

[typescript] Section

Taxus type-checks and emits plain browser JavaScript from .ts files, with no Node.js, Bun, Vite, npm install, or bundler. TypeScript support is opt-in; existing sites are unchanged.

[typescript]
enabled = true

The native compiler is also a build-time opt-in. Default Cargo builds contain no TypeScript compiler. Build a binary with the bundled compiler by enabling the Cargo feature:

cargo build -p taxus-cli --features typescript

A binary built without that feature can still use TypeScript by setting typescript.compiler to an installed Microsoft tsc executable. Taxus’s published release binaries enable this feature for their target platform.

Library-only builds can disable the product’s embedded WASM client with --no-default-features; such builds can process sites initialized with --no-islands without requiring the workspace’s taxus-client crate.

The vendored compiler archives and their pinned digests can be checked with:

python3 scripts/check-typescript-vendor.py

When updating TypeScript, run the updater with the new official release:

python3 scripts/update-typescript-vendor.py --version 7.0.3

Review the resulting binary/documentation diff, then run the checker before committing. The updater refreshes the six archives, hashes, cache version, license, and notice files.

Place TypeScript sources under scripts/ and configure them in the site-root tsconfig.json. Taxus runs Microsoft’s native TypeScript compiler during taxus build and every taxus serve rebuild. It type-checks before publishing emitted ES modules to dist/static/ts/; a failed type check fails the build and leaves the previous compiled script directory intact. taxus build --dry-run runs the checker without emitting files.

This is a compiler, not a bundler: use relative ES module imports that browsers can resolve. Include the .js extension in relative imports so the emitted modules work directly in browsers; TypeScript’s bundler resolution maps those imports back to the corresponding .ts sources during type-checking. Set sourceMap = true in compilerOptions when you want browser developer tools to map generated JavaScript back to the original TypeScript files. Npm package imports and features requiring bundling are outside this compiler workflow. TypeScript-enabled binaries bundle the official native compiler for the target platform. Taxus’s release targets are covered for macOS arm64/x64, Linux arm64/x64, and Windows arm64/x64. Other platforms can use a compatible Microsoft tsc executable by setting compiler:

[typescript]
enabled = true
compiler = "/path/to/tsc"

The taxus init --typescript option creates scripts/main.ts, an imported scripts/greeting.ts example module, and tsconfig.json, enables the setting, and adds the module script to the base template. It omits the JavaScript-mode static/scripts.js starter and script reference, so a fresh scaffold chooses one client-script mode rather than loading both. Without that flag, the JavaScript starter remains and TypeScript is disabled.

[feed] Section

RSS/Atom feed configuration for content syndication.

[highlight] Section

Syntax highlighting configuration for code blocks.

See Syntax Highlighting for details on styling and supported languages.

[images] Section

Responsive image processing configuration for hero images.

See Images for details on hero images and template usage.

[markdown] Section

Markdown rendering options.

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"
flatten = ["blog/*"]

[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)
• each [build] flatten pattern must be non-empty and must not start with /, contain .., contain an empty segment (blog//x), or use **; the error names the offending pattern

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)