Themes

Themes let you share templates, components, filters, functions, data, and public assets across projects.

Configure a theme with theme.source:

theme:
  source: "./themes/clean"

What Themes Can Provide

A theme can contain these top-level directories:

templates/
components/
filters/
functions/
data/
public/

Other top-level directories are ignored by the theme overlay.

JavaScript files under filters/, functions/, and data/ are trusted build code. Review remote themes before using them and prefer immutable tags or commit references for reproducible builds.

Project Files Override Theme Files

Veta composes the theme and project into one filesystem. Project files win over theme files.

Example:

theme/templates/base.j2
templates/base.j2

The project's templates/base.j2 overrides the theme template.

This lets a project use most of a theme while customizing selected files.

Local Themes

Use a relative path:

theme:
  source: "./themes/blog"

The path is resolved from the project root.

GitHub Themes

Remote theme sources use a GitHub-style reference:

theme:
  source: "owner/repository@ref"

Use tags or commit references when you want reproducible builds.

Veta caches remote themes under its runtime cache directory.

Pages Stay In The Project

Themes provide building blocks. Projects still declare the pages they want to output through pages/*.js.

This keeps site structure explicit and prevents a theme from unexpectedly creating routes.

Theme Data

Themes can provide data files, but project data can override them. A common pattern is:

theme/data/theme.json
data/theme.json

The project file can customize names, colors, navigation, or other theme-facing values.

Data overrides use the relative path without its extension. The project may therefore replace a theme data file while choosing a different supported format:

theme:   data/site.json
project: data/site.yaml

Both files represent data.site, so only the project YAML file is loaded. Veta still rejects multiple files for the same data key within the project or within the theme, such as data/site.json and data/site.yaml side by side.

Theme Configuration Defaults

When building reusable themes, prefer exposing user-configurable defaults through data/site_defaults.yaml in the theme. Projects can then override only the values they care about with data/site.yaml:

theme/data/site_defaults.yaml
data/site.yaml

This keeps the theme defaults and project overrides available as separate template values:

data.site_defaults
data.site

Example theme defaults:

# theme/data/site_defaults.yaml
name: "Clean Theme"
description: "A clean Veta site."

brand:
  color: "blue"
  logo: "/images/logo.svg"

Example project overrides:

# data/site.yaml
name: "My Site"

brand:
  color: "purple"

Then theme templates can prefer project values and fall back to theme defaults:

{% if data.site and data.site.name %}
  {{ data.site.name }}
{% else %}
  {{ data.site_defaults.name }}
{% endif %}

Use this pattern when you want partial project customization. If a theme and the project both provide the same logical data path, the project file replaces the theme file completely, even when their extensions differ.

Veta does not deep-merge data files automatically. Keep fallbacks explicit in templates so theme behavior stays easy to understand.