Data

Global data lives in data/. Veta loads data before page generation and exposes it as data in JavaScript generators, templates, components, and filters.

Supported Formats

Veta supports:

.json
.yaml
.yml
.toml
.js

Examples:

data/site.json
data/navigation.yaml
data/theme.toml
data/github.js

Data Keys

Data keys come from file paths without extensions:

data/site.json              -> data.site
data/navigation.yaml        -> data.navigation
data/theme/colors.toml      -> data.theme.colors

Data file stems must be valid JavaScript-style identifiers. Prefer names like site.json, navigation.yaml, and theme/colors.toml. Avoid names like site-name.json because hyphens do not produce ergonomic template keys.

Site Data Convention

Use data/site.yaml for project-level values such as site name, description, brand settings, and other values shared across templates:

name: "My Site"
description: "A site built with Veta."

brand:
  color: "purple"

This convention is optional, but it gives projects and themes a predictable place for site-wide settings.

Reusable themes should put configurable defaults in data/site_defaults.yaml instead of data/site.yaml. Projects can then provide data/site.yaml with only the values they want to customize. See Themes for the recommended theme defaults pattern.

JSON Data

{
  "name": "Veta Docs",
  "description": "Documentation built with Veta."
}

Use it in a template:

<title>{{ data.site.name }}</title>

YAML Data

main:
  - label: Home
    href: /
  - label: Docs
    href: /docs/

Use it in a template:

{% for item in data.navigation.main %}
  <a href="{{ item.href }}">{{ item.label }}</a>
{% endfor %}

YAML data files support one YAML document. Multiple YAML documents in one file are rejected.

TOML Data

name = "Clean"

[colors]
primary = "blue"

Use it in a template:

<p>{{ data.theme.colors.primary }}</p>

JavaScript Data

JavaScript data files export a default function and return a value:

export default function({ env, httpClient, parse }) {
  if (env.VETA_MODE === "development") {
    return { stars: 0, repo: "local/mock" };
  }

  const response = httpClient.get(
    "https://api.github.com/repos/varavelio/veta",
  );
  const repo = parse.json(response.body);

  return {
    repo: repo.full_name,
    stars: repo.stargazers_count,
  };
}

Data JavaScript is synchronous. Return plain JSON-compatible data. Promises are not supported.

Duplicate Keys

These files conflict because both try to define data.site:

data/site.json
data/site.yaml

These also conflict because one file tries to define data.shop while another tries to define data.shop.products:

data/shop.json
data/shop/products.json

Veta fails the build instead of guessing which value should win.

Data Versus File API

Use data/ for global data that should be loaded once and shared everywhere.

Use the JavaScript file API for content collections and project files you want to enumerate manually:

const posts = files.listFiles("content/posts/**/*.md");

Templates can also load local or remote data on demand with load_data:

{% set navigation = load_data("data/navigation.yaml") | parse_yaml %}

Use load_data for data that is only needed by a specific template, include, or component.