# Site

https://vowel.cc/docs/guides/site

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.

```yaml
--- 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](https://vowel.cc/docs/guides/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](https://vowel.cc/docs/guides/site#heading_markdown-mirrors))                                                                           |
| `robots`              | object         | Crawler rules for `robots.txt`; root only (see [robots.txt](https://vowel.cc/docs/guides/site#heading_robotstxt))                                                                                                     |
| `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](https://vowel.cc/docs/guides/site#heading_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

```yaml
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](https://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.

> [!WARNING]
> Mirrors let AI crawlers in. With `markdown_mirror: true`, the generated `robots.txt` allows the `ai` group unless your `robots` setting says otherwise, because mirrors are for AI agents. To keep them out, set `ai: false`.

## robots.txt

Vowel writes a `robots.txt` that blocks AI crawlers and image crawlers and allows everything else. With [markdown mirrors](https://vowel.cc/docs/guides/site#heading_markdown-mirrors) on, it allows AI crawlers too. Change that from the root `settings.md`:

```yaml
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](https://vowel.cc/docs/guides/files#heading_automatic-pages)), 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](https://vowel.cc/docs/references/vowel#heading_output)).

To deploy to Cloudflare Pages, install [Wrangler](https://developers.cloudflare.com/workers/wrangler/), name your Pages project in the root `settings.md`:

```yaml
cloudflare_project: my-site
```

then run:

```bash
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](https://standard.site/) documents, Bluesky posts, calendar events, or anything else with a published lexicon.

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

```yaml
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](https://vowel.cc/docs/guides/files#heading_secret-pages) 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`:

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

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

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

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

```bash
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](https://vowel.cc/docs/references/vowel#heading_output)), readable only by you. Nothing is saved if the password is wrong.
