## 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.


# 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:

```txt
.json
.yaml
.yml
.toml
.js
```

Examples:

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

## Data Keys

Data keys come from file paths without extensions:

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

```yaml
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](/docs/guides/themes/) for the recommended theme defaults pattern.

## JSON Data

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

Use it in a template:

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

## YAML Data

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

Use it in a template:

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

```toml
name = "Clean"

[colors]
primary = "blue"
```

Use it in a template:

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

## JavaScript Data

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

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

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

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

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

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

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