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.
Run
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:
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:
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:
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.