# vowel

https://vowel.cc/docs/references/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.

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

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

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

```bash
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](https://vowel.cc/docs/guides/site), and page properties in [Markdown](https://vowel.cc/docs/guides/markdown#heading_frontmatter).

## 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](https://vowel.cc/docs/references/vowel#heading_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](https://vowel.cc/docs/guides/markdown#heading_url-thumbnails), in `$links/`, because a fetched page can't be rebuilt from your files.
