Site-wide settings go in the frontmatter of a settings.md file. A settings.md applies to its folder and every folder beneath it, and a setting in a subfolder overrides the same setting above it. A key left empty, like author: with nothing after it, is not set: in a subfolder, it removes the setting from above. The file itself is not a page.
---
name: My Blog
domain: example.com
logo: logo.svg
---
The site's name is the root settings.md's name, shown in the header of every page. A page's <title> is its own title, then each folder above it, then the site's name: "First Post - Blog - My Blog". A folder is named by its index page: that page's breadcrumb, else its title, else the folder's name. To rename the blog in titles and menus, give blog.md a title or a breadcrumb.
Paths (logo, wordmark, icon, social link icons and the publication's icon) are URL paths from the root: logo: logo.svg and logo: /logo.svg are the same file. ./logo.svg means the settings file's own folder.
Key
Type
Meaning
name
text
The site's name, shown in the header and at the end of page titles; root only
domain
text
The site's domain, such as example.com. Needed for the sitemap, the feed, canonical links and AT Protocol. Left empty, it is a warning until you set it or remove it. domain: false also means the site has none.
author
text
The feed's author, for posts that name none
logo
path
A logo image for the header
wordmark
path
A wordmark image for the header
icon
path
The favicon
fallback_image
path
The image for link previews ( og:image) of a page that has no image of its own
styles
paths
Stylesheets for the pages here and below, besides styles.css (see [[Design#CSS
theme
name or object
Reset, Typography or Default, or {name, colors, …} with colour and typography settings (see Design)
social_links
list
{label, url, icon} links; a folder's list replaces its parent's
feed_limit
number
How many posts the feed carries. Default 20.
markdown_mirror
boolean
true publishes every page as markdown too; root only (see Markdown mirrors)
robots
object
Crawler rules for robots.txt; root only (see robots.txt)
cloudflare_project
text
The Cloudflare Pages project deploy publishes to; root only
atproto_did
text
An AT Protocol account's DID
atproto_pds
URL
The account's server, to skip looking it up
atproto_lexicon
text
Publish the pages here as records of this lexicon, such as site.standard.document or app.bsky.feed.post (see AT Protocol)
atproto_content
text
The content lexicon for a record's content when it can hold any type. Default at.markpub.markdown.
atproto_publication
object
{description, icon} for the site's publication record; root only. icon is a path, and defaults to logo.
Social links
social_links:
- label: GitHub
url: https://github.com/example
icon: icons/github.svg
- label: Bluesky
url: https://bsky.app/profile/example.com
With an icon, the label is the image's alt text; without one, it is the link text. Each link carries rel="me", for Mastodon and IndieAuth verification. A folder's list replaces its parent's entirely.
Sitemap
With a domain set, Vowel builds sitemap.xml, listing every page with a URL. Leave a page out with sitemap_item: false in its frontmatter.
Without a domain there is no sitemap, because a sitemap is made of absolute URLs.
Feed
With a domain set, Vowel builds feed.xml, an Atom feed of the twenty most recent dated pages, each with its full body and absolute URLs.
Change the number of entries with feed_limit: 50, and name the feed's author with author:. A post's own author: names the author of its entry. Leave a page out with rss_item: false in its frontmatter.
A dated page with html_file: false has no page of its own, but it is still an entry, with its full body and no link. That makes a feed-only post.
Without a domain there is no feed, because every entry needs an absolute address.
Markdown mirrors
With markdown_mirror: true in the root settings.md, Vowel publishes every page a second time, as markdown, beside itself: /blog/kerning and /blog/kerning.md. Language models, AI agents and scripts read markdown more easily than a web page, and each page links its mirror from its <head>.
A mirror is the page as a reader sees it, not your source file. It starts with the page's title as a heading and a line with its date and URL. Its content follows, with listings, wikilinks and icons as the page renders them. With a domain, every link in it is absolute.
A page's own markdown_mirror overrides the root's: false leaves the page out, and true mirrors it on a site that has mirrors off. A subfolder's settings.md can't set it.
A page with html_file: false and markdown_mirror: true is published only as markdown. Nothing on the site links to it. The root's markdown_mirror alone doesn't mirror a page without a file.
With a domain as well, Vowel writes llms.txt, a table of contents of the mirrors for language models, in the format llmstxt.org proposes. It lists your root pages, then a section for each top-level folder, each page with a link to its mirror and its description. Pages that are hidden, secret or left out of their mirror aren't listed. Your own llms.txt replaces the generated one.
robots.txt
Vowel writes a robots.txt that blocks AI crawlers and image crawlers and allows everything else. With markdown mirrors on, it allows AI crawlers too. Change that from the root settings.md:
robots:
ai: false # AI training and AI search crawlers
images: false # image crawlers
search: true # search engines
all: true # every other crawler
GPTBot: true # one crawler by name, overriding its group
With a domain, it also points crawlers at the sitemap. Your own robots.txt replaces the generated one.
Generated files
Besides pages (see Files), Vowel generates these files:
File
When
/sitemap.xml
With a domain
/feed.xml
With a domain
/robots.txt
Without your own robots.txt
/llms.txt
With markdown_mirror and a domain
/.well-known/atproto-did
With atproto_did
/.well-known/site.standard.publication
With atproto_did and a domain
A file of your own at any of these paths replaces the generated one.
Deploying
The built site is a folder of static files, so any static host works. Vowel builds into a folder outside your project (see Output).
To deploy to Cloudflare Pages, install Wrangler, name your Pages project in the root settings.md:
cloudflare_project: my-site
then run:
vowel --command deploy
This builds the site, waits for images and link previews to finish, and runs wrangler pages deploy on the output. Wrangler reads your Cloudflare credentials from CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID. --payload '{"projectName":"other-site"}' deploys to another project, and --payload '{"dryRun":true}' builds without deploying.
AT Protocol
Vowel can verify your site's domain as a Bluesky handle, and publish your pages as AT Protocol records: standard.site documents, Bluesky posts, calendar events, or anything else with a published lexicon.
domain: example.com
atproto_did: did:plc:abc123
With atproto_did set, the site serves your DID at /.well-known/atproto-did, which is how a domain proves it is an account's handle. Deploy, then set the domain as your handle in your Bluesky settings.
To publish pages as records, set atproto_lexicon on a folder's settings.md, or in one page's frontmatter:
atproto_lexicon: site.standard.document
A lexicon is a record type's schema, named like a reversed domain (app.bsky.feed.post, community.lexicon.calendar.event). Vowel includes none: when you publish, it looks each one up where its owner publishes it and fills a record from your page as well as it can. A lexicon that isn't published this way can't be used. Each page publishes to one lexicon, and needs a domain.
Each record gets a fixed address built from the page's URL. Pages in a secret folder are only published when the lexicon is set inside that folder or on the page itself, and a page with status: hidden is never published.
A record's properties come from the page's frontmatter, by name, and from what Vowel reads from the page, under a few common names. Write starts_at or startsAt for a startsAt property; if you write both, startsAt wins. Nested YAML fills a nested object, and a value that can be one of several types names its type with $type:
starts_at: 2026-10-14T19:00-04:00
mode: community.lexicon.calendar.event#inperson
locations:
- $type: community.lexicon.location.address
locality: Toronto
country: CA
From the page itself, a record's title or name is the page's title, description its description, tags its tags and hashtags, image its image, publishedAt (or else createdAt) its date, and content (or else text) its body. Keys Vowel uses for itself, such as title, tags, status and image, don't fill properties by name.
The body is the rendered page without its title. When the lexicon has facets beside text, as Bluesky posts do, the body is plain text, with its links, hashtags and any formatting the lexicon supports marked as facets. Otherwise it is simplified markdown: links and images point at your site, icons become emoji where there is one, a listing becomes a list of links, and hashtags link to their tag pages. When content can hold any type of content, as standard.site's can, the markdown is published as an at.markpub.markdown object; set atproto_content in settings.md to use another content lexicon.
Text that is too long is trimmed at a word, and a list that is too long is cut. A page missing a property the lexicon requires, or with a value it can't use, isn't published, and atproto-publish warns which property it was. Uploading files, such as images for a property that needs one, isn't supported yet.
For a site.standard.document, site and path are filled as standard.site defines them, and the page links to its record with <link rel="site.standard.document">.
When any page publishes to standard.site, the site is a site.standard.publication, and each document names it. Its name is the root name; a description and an icon go in the root settings.md:
atproto_publication:
description: Notes and experiments
icon: mark.svg
The icon defaults to logo. It is published as a 512-pixel square PNG. With a domain, the site serves the publication's address at /.well-known/site.standard.publication, which is how your domain claims it.
Publishing is a separate command, so nothing reaches the network while you write:
ATPROTO_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx vowel --command atproto-publish
The command builds the site, compares the publication and the records with the ones on your account, and creates and updates records to match. Run it with --payload '{"dryRun":true}' to see what it would change without sending anything.
It never deletes a record on its own, even when you remove the page: to delete a page's record, set status: deleted on the page and publish again. The publication is created and updated, never deleted.
To deploy and then publish in one step:
vowel --command publish
A site without atproto_did is only deployed. If the deploy fails, nothing is published. --payload '{"dryRun":true}' shows what both steps would do without sending anything.
Create an app password in your Bluesky settings. Instead of the environment variable, save it once with:
vowel --command atproto-password
It asks for the password without showing it, checks it by logging in to the account in atproto_did, and saves it in a file named atproto-app-password in the project's system folder (see Output), readable only by you. Nothing is saved if the password is wrong.