# votive

https://vowel.cc/docs/references/votive

`votive` is the engine Vowel is built on. It turns a folder of source files into a folder of built files, and keeps a database of what depends on what, so that an edit rebuilds only what it affects. `votive` knows nothing about markdown, HTML or blogs; every Vowel feature is a `votive` plugin.

> [!CAUTION] Internal, for now
> `votive` is an internal tool. It isn't meant for public use yet, and its API changes without notice, between any two releases. This page describes it as it is today, for anyone reading Vowel's source; don't build on it.

## Run

```js
import votive from "votive" const site = await votive(config) const { deferred } = await site.build() await deferred await site.close()
```

`site.build()` resolves when the pages are written. Slow work, such as resizing images and fetching URLs, carries on in the background; `deferred` resolves when it is done and the site has been rebuilt with the results. Pass `{defer: false}` to skip the background work.

Pass `{changed, deleted}`, as arrays of paths relative to the source folder, to rebuild only what those files affect. Without them, `votive` scans the whole folder. Concurrent calls are merged into one build.

| Member                                    | Meaning                                                    |
| ----------------------------------------- | ---------------------------------------------------------- |
| `site.build(options)`                     | Runs a build; resolves to `{deferred}`                     |
| `site.database`                           | The build database                                         |
| `site.on("built" \| "deferred", handler)` | Called after each build, and when background work finishes |
| `site.close()`                            | Closes the database                                        |

`startServer(config)` builds, watches the source folder, and serves the output with live reload. It resolves to `{port, server, close}`. `runCommand(config, name, payload)` runs a plugin's command without a server.

To add plugins to Vowel rather than start from scratch, use Vowel's config, which adds yours after its own:

```js
import votive from "votive" import { createConfig } from "vowel/config.js" const site = await votive(createConfig("/path/to/site", { plugins: [myPlugin] }))
```

`import vowel from "vowel"` and `vowel({ sourceFolder, plugins })` does the same and starts the preview server.

## Config

| Key                                                                 | Meaning                                                                                          |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `sourceFolder`                                                      | Absolute path to the source files. Required.                                                     |
| `targetFolder`                                                      | Where built files go. Required.                                                                  |
| `databasePath`                                                      | The build database. `":memory:"` keeps it in memory.                                             |
| `cacheDirectory`                                                    | Where background results, such as resized images, are cached                                     |
| `plugins`                                                           | The plugins, in order                                                                            |
| `router(sourcePath)`                                                | Rewrites every source path before any processor routes it. Return nothing to leave a path alone. |
| `log(level, message)`                                               | Receives `"error"`, `"warn"` and `"info"` messages. Defaults to the console.                     |
| `verbose`                                                           | Log `info` messages with the default logger                                                      |
| `urlStore`                                                          | Where fetched URLs are kept, relative to `sourceFolder`. Default `.urls`.                        |
| `userAgent`, `urlFetchTimeout`, `urlConcurrency`, `urlHostInterval` | How URLs are fetched                                                                             |

## Plugins

A plugin is an object with a name, processors, and optionally commands:

```js
export default { name: "my-plugin", processors: [ /* … */ ], commands: { "my-command": async (payload, { config, notify }) => { /* … */ } } }
```

A processor claims files by extension and says how to read, route and write them:

```js
const txtProcessor = { extensions: [".txt"], format: "text", // "text", "buffer" or "url" router: ({ dir, name }) => ({ dir, name, ext: ".html" }), readFile: (source) => ({ data: source.text, metadata: { words: source.text.split(/\s+/).length } }), writeFile: (target) => ({ data: `<pre>${target.data}</pre>` }) }
```

A **source** is a file in the source folder. A **target** is what it becomes: a path, `data` (its content), and `metadata`. Every source routes to at most one target.

## Hooks

Every hook takes `(subject, context)`, and `context` is always `{api, settings, config}`.

| Hook            | Subject                                                  | Runs                                                             |
| --------------- | -------------------------------------------------------- | ---------------------------------------------------------------- |
| `router`        | `{dir, name, ext, inRootDir}`                            | For every source. Return where it lands, or `false` for nowhere. |
| `readFile`      | `{path, target, text, buffer(), stream()}`               | When a source is new or changed                                  |
| `readBuffer`    | the same, bytes only                                     | Like `readFile`, in the background                               |
| `transformFile` | the stored target                                        | After a read, once every target in the build exists              |
| `writeFile`     | the stored target, with `buffer()` and `stream()`        | When the target is stale                                         |
| `readURL`       | `{url, status, redirect, text(), json(), arrayBuffer()}` | When a URL a hook asked for is fetched                           |
| `createStubs`   | –                                                        | Every build; declares generated sources                          |
| `expandStubs`   | a stub `{path, params}`                                  | When a stub is new or its params changed                         |

A hook that throws is logged with the hook, plugin and file, and the rest of the build carries on. The exception is `createStubs`: a throw there stops the build. `readFile` and `readBuffer` get no `settings` and a write-only `api`: they run before the things they might ask about exist.

`readFile`, `readBuffer` and `transformFile` all return the same optional shape:

| Key        | Meaning                                                                                      |
| ---------- | -------------------------------------------------------------------------------------------- |
| `data`     | The target's content                                                                         |
| `metadata` | The target's properties. `{$type, $value}` declares a value's type.                          |
| `settings` | Settings this source contributes to its folder                                               |
| `write`    | `false` makes the target virtual: its `writeFile` runs, but nothing is written to disk       |
| `targets`  | Extra targets this source owns, such as an image's resized copies. They are deleted with it. |

A read's result replaces the target's metadata; a transform's result is merged into it.

`writeFile` returns `{data, encoding}` to write the file. `{delete: true}` removes the target and its file. Returning nothing leaves the target as it is and marks it fresh. Whatever `writeFile` returns becomes the target's `data`, so a later `writeFile` sees the rendered output, not the input.

## The api

`context.api` reads the database, and records what each hook read so it can be rerun when that changes.

| Method                                                    | Returns                                                                                   |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `api.target(path)`                                        | One target by its path                                                                    |
| `api.targetBySource(sourcePath)`                          | The target a source routed to                                                             |
| `api.targets({folder, recursive, query, orderBy, limit})` | Targets in a folder                                                                       |
| `api.url(url)`                                            | The data `readURL` stored for a URL, or `undefined` while it is fetched in the background |

Reads are tracked per property: a page that read another page's `title` is rebuilt when that title changes, and not when its body does. A listing is also rebuilt when a target joins or leaves it.

`query` filters `api.targets()` by metadata:

| Query                          | Matches                    |
| ------------------------------ | -------------------------- |
| `{status: "draft"}`            | `status` equals `"draft"`  |
| `{status: null}`               | no `status`                |
| `{tags: {"~": "design"}}`      | `tags` contains `"design"` |
| `{date: {">=": "2026-01-01"}}` | also `>`, `<`, `<=`        |
| `{"\|": {a: 1, b: 2}}`         | either condition           |
| `{"!": {status: "draft"}}`     | not                        |

Conditions in one object must all match. `orderBy` is `{property, direction}`, with `direction` `"asc"` or `"desc"`.

## Settings

`context.settings` is the view of every `settings` value contributed at the subject's folder and each folder above it. Read it through its methods, which take a label:

| Method                         | Returns                                                              |
| ------------------------------ | -------------------------------------------------------------------- |
| `settings.lastNonNull(label)`  | The nearest folder's value: the usual override rule                  |
| `settings.firstNonNull(label)` | The root-most value, for site-wide settings                          |
| `settings.last(label)`         | The subject's own folder's value, or `null`                          |
| `settings.flat(label)`         | Every value from root to folder, as one array                        |
| `settings.raw(label)`          | One slot per folder from the root, each an array of values or `null` |

A label that was never set returns `undefined`, or `[]` from `flat`. The view is read-only; a plugin contributes settings only by returning them from a read hook.

## Stubs

A stub is a generated source: a tag page, a folder index, a feed. `createStubs` returns `[{path, params}]` on every build, and `expandStubs` turns a stub into content, as `{text}` or `{buffer}`, only when its `params` change. The content is then read by whichever processor claims the stub's extension, as if it were a file. A real file at the same path replaces the stub.

`createStubs` gets an untracked `api` with `target`, `targetBySource`, `targets`, `metadataValues(label)` and `settingValues(label)`, and the root's `settings`.

## Commands

A command is a function a plugin names: `(payload, {config, notify}) => result`. Run one with `runCommand(config, name, payload)`, or from Vowel's CLI with `vowel --command <name> --payload <json>`. `notify({status, message})` reports progress.

The dev server also accepts commands, from the page it serves, but only when it listens on your own machine.
