Vowel

vowel

vowel is an npm package for generating a website from markdown.

vowel needs Node.js 26 or later.

Run vowel in your project folder. It builds the site, serves a preview at http://localhost:8000 (or the next free port), and rebuilds as you edit. The preview updates open pages in place, without reloading.

npx vowel@latest

In a folder without a settings.md, a setup wizard offers to write one, and a home.md. It also offers two files for AI agents: an AGENTS.md, and the Vowel skill for Claude Code in .claude/skills/vowel/. It never replaces a file you already have. Press Ctrl-C to leave it; nothing is written until the end. If the folder has no markdown files but other things in it, or is your home folder, vowel asks before setting up a site there. Without a terminal (in CI, or piped), the wizard is skipped.

To set up a site without starting the preview, run vowel init. With no options, in a terminal, it runs the wizard. With options, which answer the wizard's questions, it asks nothing, so a script or an AI agent can set up a site in one command:

vowel init --name "My Site" --domain example.com --agents
Option Effect
--name <text> The site's name, in settings.md
--domain <domain> The site's domain, in settings.md
--theme <name> default, typography or reset
--author <text> The feed's author
--slogan <text> The homepage's slogan
--no-home Don't write a home.md
--agents Write an AGENTS.md
--skill Add the Vowel skill to .claude/skills/vowel/
--force Set up a site even in a folder with no markdown and other files in it, or in your home folder

What you don't give gets a default: the name "Site Name", the default theme, and an empty domain: and author: in settings.md for you to fill in. vowel init says which defaults it used. Run with no options and no terminal, it writes only defaults. The wizard suggests the folder's name as the site's name, which you can change before anything is written.

An empty domain: is a warning, in every build and in vowel check, until you set it or remove it.

Without a terminal, vowel init refuses such a folder unless you pass --force. A misspelled option is an error.

To build the site into a folder of your own, to upload anywhere or keep:

vowel export ../my-site

The folder must be new or empty, and outside your project.

To check the site for problems before you publish it:

vowel check

It builds the site once and lists every warning and error, each at its place in your files, such as home.md:6:15: link to /nowhere matches no page. Most editors and terminals open that line when you click it. If there were any problems, vowel check exits with code 1; otherwise it exits with 0. A warning counts, because a link that would 404 is a warning. It changes nothing in your project or in the preview, so it is safe to run in CI or from an AI agent that has edited your site.

The preview server only listens on your own machine.

Settings are listed in Site, and page properties in Markdown.

Flags

Flag Effect
--skip Skip the setup wizard
--clear Discard the build cache and output, and build from scratch. --reset is the same.
--logging=verbose Log every build step. essential is the default; silent logs nothing.
--command <name> Run a command instead of the preview (see Commands)
--payload <json> The command's options, as JSON

Commands

Command Payload Effect
deploy {"projectName": "…", "dryRun": true} (optional) Builds the site and deploys it to Cloudflare Pages with Wrangler (see [[Site#Deploying
publish As deploy deploy, then atproto-publish if the site has an atproto_did
export {"path": "…"} Builds the site and copies it to a new or empty folder outside the project. vowel export <folder> is the same.
check None Builds the site, lists its warnings and errors, and exits with 1 if there are any. vowel check is the same.
atproto-password {"password": "…"} (optional) Asks for your app password, checks it against atproto_did, and saves it for atproto-publish
atproto-publish {"dryRun": true} (optional) Creates and updates your pages' AT Protocol records, and deletes those of pages with status: deleted (see [[Site#AT Protocol

export and check can be run as words, like vowel init; every other command needs --command. A word vowel doesn't know is an error, rather than starting the preview.

Output

vowel keeps its build output, its build cache and its database outside your project, in a folder per project:

Platform Location
macOS ~/Library/Application Support/votive/<id>/
Linux $XDG_DATA_HOME/votive/<id>/, or ~/.local/share/votive/<id>/
Windows %LOCALAPPDATA%\votive\<id>\

<id> is derived from the project folder's path. The built site is in output/. The database and cache are rebuilt from your files, so deleting the folder, or running with --clear, loses nothing.

The one thing vowel writes into your project is fetched link previews, in $links/, because a fetched page can't be rebuilt from your files.