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


# Pages

Pages are generated by JavaScript files in `pages/`. Each file must export a default function that returns an array of page objects.

```js
export default function({ data, parse }) {
  const { html } = parse.markdown(`# ${data.site.name}`);

  return [
    {
      permalink: "/",
      template: "base",
      title: "Home",
      content: html,
    },
  ];
}
```

## Directory Rules

`pages/` is flat. This is valid:

```txt
pages/site.js
pages/posts.js
```

This is not valid:

```txt
pages/blog/posts.js
```

Use multiple files when it helps organize generators, but keep them directly inside `pages/`.

## Page Object Contract

Every page object must have `permalink`.

```js
{
  permalink: "/docs/intro/",
  template: "base",
  title: "Intro",
  content: "<h1>Intro</h1>"
}
```

Fields:

- `permalink` is required and must be a string.
- `template` is optional and must be relative to `templates/`.
- `content` is optional and defaults to an empty string.
- Any extra fields are preserved and exposed to templates through `page`.

`layout` is not supported. Use `template`.

## Permalinks And Output Paths

Veta normalizes permalinks into output paths:

```txt
/                  -> index.html
/about/            -> about/index.html
/feed.xml          -> feed.xml
/llms.txt          -> llms.txt
```

If the last permalink segment has an extension, Veta writes that exact file path. Otherwise, it writes an `index.html` file under the permalink path.

## Templated Pages

When `template` is present, Veta passes `content` unchanged and trusted to the named template. It does not automatically render Markdown or resolve components. The generator must return the final format that the template expects, usually HTML.

```js
export default function({ parse }) {
  const source = "This supports **Markdown** and <note>components</note>.";
  const { html } = parse.markdown(source);
  const content = parse.renderComponents(html);

  return [
    {
      permalink: "/about/",
      template: "base",
      title: "About",
      content,
    },
  ];
}
```

The template receives that final string as `page.content`. Use `parse.markdown(text)` and `parse.renderComponents(text)` explicitly, in the order required by the content.

## Raw Pages

When `template` is omitted, Veta writes `content` directly.

```js
{
  permalink: "/feed.xml",
  content: `<feed><title>${data.site.name}</title></feed>`,
}
```

Raw pages are useful for feeds, sitemaps, JSON, text files, Markdown files, and any other generated asset.

Because raw output is not transformed either, a generator can intentionally return Markdown, JSON, XML, or plain text without a template.

## Output Collisions

Two page objects cannot write the same output path. Veta reports an error if generators produce conflicting permalinks.

## Generating Pages From Files

Use the JavaScript file API to generate content-driven pages:

```js
export default function({ files, parse }) {
  return files.listFiles("content/posts/**/*.md").map((path) => {
    const { frontmatter, html } = parse.markdown(files.readFile(path));
    const content = parse.renderComponents(html);

    return {
      permalink: files.toPermalink(path, { stripPrefix: "content" }),
      template: "post",
      title: frontmatter.title,
      content,
    };
  });
}
```