Configuration

Rockgarden follows a progressive customization model: sensible conventions are the defaults, and everything is configurable. A site with zero configuration works out of the box. Add options as your needs grow.

Configuration lives in rockgarden.toml at the site root.

[site]

URL Styles

Controls how filenames are transformed into URLs. Given a file Session Logs/2026-03-21 - Session 40.md:

• slug: Lowercases, replaces spaces and underscores with dashes, collapses consecutive dashes.
• preserve-case: Same as slug but keeps the original casing from filenames.
• preserve: Keeps filenames exactly as-is (spaces, casing, characters). URLs are percent-encoded.

All styles strip the .md extension and preserve directory structure. Per-page slug frontmatter overrides any style.

[site]
url_style = "preserve-case"

Folder URLs

A folder renders at /folder/ when it contains either:

• index.md — the canonical form
• a folder-note: a file matching the folder name, e.g. attend/attend.md (Obsidian folder-note convention). The slug is rewritten internally to attend/index.

Both forms produce the same URL (/attend/) and are interchangeable. When both index.md and a folder-note coexist, index.md wins and a warning is logged.

To place a page literally at /folder/folder/ (bypassing the folder-note rewrite), set an explicit slug in the page's frontmatter:

---
slug: attend/attend
---

[build]

[theme]

Theme-specific display and rendering options. These are supported by the default theme. Custom themes may support different options.

[nav]

Per-folder sort overrides

Override sort and reverse for specific folders via config or per-folder metadata file.

In rockgarden.toml:

[nav.overrides.blog]
sort = "date"
reverse = true

In a folder's _folder.md frontmatter (takes priority over config):

---
sort: date
sort_reverse: true
---

Priority: _folder.md > [nav.overrides.<path>] > global [nav] defaults.

The "date" sort strategy orders by file modified time and is only available on folder index pages. In the nav sidebar, "date" falls back to "files-first".

Folder Metadata (_folder.md)

An optional _folder.md file inside any content folder holds folder-level metadata. Only the frontmatter is consumed — any body content is ignored. The file is not published as a page and is not indexed for wiki-link resolution.

Supported fields:

_folder.md is strictly optional — folders work without one, using defaults.

[feed]

Atom feed generation. Requires site.base_url to be set.

[toc]

[search]

[dates]

[llms_txt]

Generates an llms.txt file following the llmstxt.org specification, making site content discoverable by LLMs. Requires site.base_url to be set.

Pages are grouped by named collection first, then by top-level directory, then root-level pages.

[hooks]

Shell commands executed at build lifecycle stages. Commands run sequentially; any non-zero exit aborts the build.

See Build Hooks for environment variables, content JSON export, and examples.

[[collections]]

Repeatable section. Each defines a named content collection with its own namespace.

Supported file formats: .md, .yaml, .yml, .json, .toml

Collections are available in templates as collections.<name>.

Frontmatter Fields

Per-page options set in YAML frontmatter:

CLI Overrides

Command-line flags override config file values:

rockgarden build                          # full build, overwrites in place
rockgarden build --clean                  # delete output dir first, then build
rockgarden build --incremental            # skip unchanged pages (faster rebuilds)
rockgarden build --source ./vault --output ./dist
rockgarden build --config ./custom.toml
rockgarden serve --output ./dist --port 3000

Build modes

• build — Renders all pages and writes output. Existing files are overwritten but stale files from renamed/deleted pages are not removed. Use --clean periodically to avoid accumulation.
• build --clean — Deletes the output directory before building. Guarantees a fresh output with no stale files.
• build --incremental (-i) — Skips rendering pages whose source file hasn't changed since the last incremental build. Global outputs (folder indexes, search index, sitemap, feed, tags) always regenerate. A build manifest is stored in .rockgarden/build-manifest.json. Changes to config, templates, or macros trigger a full rebuild automatically. Renamed or deleted pages have their stale output files cleaned up.

Convention Directories

These directories are discovered by convention at the site root (the directory containing rockgarden.toml), not inside the source directory: