Customization

Rockgarden supports progressive customization — start with zero config and add layers as needed.

Convention directories like _styles/, _scripts/, _static/, and _templates/ are resolved relative to the site root — the directory containing rockgarden.toml. When your source directory is a subdirectory (e.g. source = "vault"), place these directories next to rockgarden.toml, not inside the source directory.

Static Files

Place files in _static/ at your site root to have them copied as-is to the output root during build. Useful for deployment platform files (_redirects, _headers), favicons, robots.txt, and verification files.

Files in _static/ are copied late in the build and overwrite any generated output at the same path.

Custom CSS and JavaScript

Drop files in _styles/ and _scripts/ at your site root. They are automatically copied to the output directory and injected as <link> / <script> tags.

Template Overrides

Place template files in _templates/ to override individual components without replacing the entire theme. For example, _templates/components/nav.html overrides just the navigation component.

Templates are resolved in order: site _templates/ → named theme → built-in default. First match wins.

Named Blocks

page.html exposes Jinja2 blocks as extension points:

Use {% extends "page.html" %} and override specific blocks. Use {{ super() }} to extend a block rather than replace it.

Layout System

Layouts define page structure. The default layout is layouts/default.html (sidebar navigation with content area).

Select a layout per page via frontmatter:

---
layout: talk
---

This resolves to layouts/talk.html. Resolution order: frontmatter layout → collection default → [theme] default_layout → layouts/default.html.

Theme Options

The [theme] table includes options that control the default layout appearance.

Content Padding

Control the horizontal padding of the main content area with a Tailwind CSS padding class:

[theme]
main_content_padding = "px-12"

Default: px-12. Pre-built values available without a custom CSS build: px-4, px-6, px-8, px-10, px-12, px-16, px-20, px-24. The class is applied at the lg breakpoint; mobile padding remains p-4.

For values outside this range, you'll need a custom Tailwind CSS build — see Custom Themes or export the default theme with rockgarden theme export.

Theme Export

To fully customize the default theme, export it as a starting point:

rockgarden theme export

This copies all default templates and CSS source to _themes/default/ and sets theme.name = "default" in your config.

Custom Themes

Place a complete theme in _themes/<name>/ and set theme.name in config:

[theme]
name = "mytheme"

A theme provides its own templates, styles, and scripts.

Collections

Collections partition content into named subsets scoped by directory. Each collection can have its own templates, URL patterns, data formats (YAML, JSON, TOML), and Pydantic model validation.

[[collections]]
name = "speakers"
source = "speakers"
template = "speaker.html"
url_pattern = "/speakers/{slug}/"

See Configuration for full collection options.

Icons

Rockgarden bundles the full Lucide icon set. Icons are available in both templates and markdown content.

In Templates

Use the icon global function or filter to render inline SVG:

{{ icon("map-pin") }}
{{ "github" | icon }}

Missing icons render as empty strings and log a warning.

In Markdown

Use :lucide-name: syntax to insert icons inline:

Click :lucide-settings: to configure.
Find us at :lucide-map-pin: 123 Main St.

Only icons that resolve successfully are replaced — unrecognized patterns are left as literal text, so the syntax degrades gracefully in other markdown renderers. Additional icon libraries may be supported in the future.

Icons inside code blocks (fenced or inline) are never processed.

To disable inline icon processing, set inline_icons = false in [build]:

[build]
inline_icons = false

Custom Icons

Place custom SVG files in an icons directory and set build.icons_dir:

[build]
icons_dir = "_icons"

Custom icons at _icons/lucide/<name>.svg override the bundled version of that icon.

Build Hooks

Run shell commands at build lifecycle stages:

[hooks]
pre_build = ["python scripts/fetch_data.py"]
post_collect = ["python scripts/generate_og.py"]
post_build = ["echo 'Build complete'"]

See Build Hooks for details.