## Documentation index

This index lists every available documentation page and its Markdown source.

- [Documentation](https://veta.varavel.com/docs/index.md)
  - [Getting Started](https://veta.varavel.com/docs/getting-started/index.md)
  - [Installation](https://veta.varavel.com/docs/installation/index.md)
  - [Guides](https://veta.varavel.com/docs/guides/index.md)
    - [Project Structure](https://veta.varavel.com/docs/guides/project-structure/index.md)
    - [Configuration](https://veta.varavel.com/docs/guides/configuration/index.md)
    - [Pages](https://veta.varavel.com/docs/guides/pages/index.md)
    - [Data](https://veta.varavel.com/docs/guides/data/index.md)
    - [Markdown](https://veta.varavel.com/docs/guides/markdown/index.md)
    - [Templates](https://veta.varavel.com/docs/guides/templates/index.md)
    - [Components](https://veta.varavel.com/docs/guides/components/index.md)
    - [Filters](https://veta.varavel.com/docs/guides/filters/index.md)
    - [Assets And Tailwind CSS](https://veta.varavel.com/docs/guides/assets-and-tailwind/index.md)
    - [Themes](https://veta.varavel.com/docs/guides/themes/index.md)
    - [Development Server](https://veta.varavel.com/docs/guides/development-server/index.md)
    - [Build And Output](https://veta.varavel.com/docs/guides/build-and-output/index.md)
    - [Deployment](https://veta.varavel.com/docs/guides/deployment/index.md)
  - [Reference](https://veta.varavel.com/docs/reference/index.md)
    - [CLI Reference](https://veta.varavel.com/docs/reference/cli/index.md)
    - [Config Reference](https://veta.varavel.com/docs/reference/config/index.md)
    - [Page Generators Reference](https://veta.varavel.com/docs/reference/page-generators/index.md)
    - [Template Context Reference](https://veta.varavel.com/docs/reference/template-context/index.md)
    - [Troubleshooting](https://veta.varavel.com/docs/reference/troubleshooting/index.md)
  - [API](https://veta.varavel.com/docs/api/index.md)
    - [JavaScript API](https://veta.varavel.com/docs/api/javascript/index.md)
    - [File API](https://veta.varavel.com/docs/api/files/index.md)
    - [HTTP Client](https://veta.varavel.com/docs/api/http-client/index.md)
    - [Parse API](https://veta.varavel.com/docs/api/parse/index.md)
    - [Template Functions](https://veta.varavel.com/docs/api/template-functions/index.md)
    - [Environment And Console](https://veta.varavel.com/docs/api/environment-and-console/index.md)
    - [Markdown Frontmatter](https://veta.varavel.com/docs/api/frontmatter/index.md)


## Documentation content

The documentation for the current page follows, reproduced verbatim.


# Themes

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

Configure a theme with `theme.source`:

```yaml
theme:
  source: "./themes/clean"
```

## What Themes Can Provide

A theme can contain these top-level directories:

```txt
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:

```txt
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:

```yaml
theme:
  source: "./themes/blog"
```

The path is resolved from the project root.

## GitHub Themes

Remote theme sources use a GitHub-style reference:

```yaml
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:

```txt
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:

```txt
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`:

```txt
theme/data/site_defaults.yaml
data/site.yaml
```

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

```txt
data.site_defaults
data.site
```

Example theme defaults:

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

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

Example project overrides:

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

brand:
  color: "purple"
```

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

```html
{% 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.