Vowel uses markdown to define most of the configuration and content of your website.
Vowel reads CommonMark, plus footnotes, highlights, strikethrough and tables from GitHub-Flavored Markdown. Raw HTML isn't rendered. Tags inside a paragraph, such as <b> or <br>, are dropped and their text is kept. A block of HTML, such as a <details> element on lines of its own, is dropped with everything in it, and so are HTML comments. Markdown between HTML tags still renders when blank lines separate it from them.
Vowel accepts the following inline markup:
Markup
Syntax
Output
Bold
**bold** or __bold__
<strong>
Italic
*italic* or _italic_
<em>
Strikethrough
~~struck~~ or ~struck~
<del>
Highlight
==highlighted==
<mark>
Inline code
`code`
<code>
Link
[text](https://example.com)
<a>; to another site, opening in a new tab, with rel=external
Link to a page
[text](./post.md), ../post.md, /blog/post.md, /about
<a> to the page's url
Autolink
<https://example.com>
<a>
Hashtag
#tag, #science/physics
<a class=hashtag href=/tags/tag>
Wikilink
[[Note]], [[Note|text]], [[Note#Section]], [[folder/Note]]
<a class=wikilink>
Wikilink to a file
[[Photo.jpeg]]
<a class=wikilink>
Emoji
:tada:
🎉
Icon
:folder/name:
<img class=icon>
Footnote
Text[^1] with [^1]: The note.
<sup> link, and a footnotes section at the end
Vowel accepts the following block-level markup:
Block
Syntax
Output
Title
# Example title at the top of the page, else rendered as a heading
<h1> as <main>'s first child
Headings
## Example heading to ###### Example heading
<h2>–<h6> with an id: heading_example-heading
Lists
- Example item, 1. Example item
<ul>, <ol>
Blockquote
> Example quote
<blockquote>
Alert
> [!NOTE] Example optional title then > Example content
<aside class="alert note"> with a heading
Code block
```example-lang … ```
<pre><code>, highlighted
Table
| a | b | with a | - | - | row
<figure class=table> with a <table>
Horizontal rule
---
<hr>. After one paragraph at the top of the page, it marks that paragraph as the description
Image

<picture>: AVIF, WebP and the original at four widths, with its size and a placeholder
Image caption
 Example caption on same line
<figure class=image> with <figcaption>
Page list
A glob path: /* or /**: /blog/*
A list of cards
Page thumbnail
A file path: /about
A card for that page, <article class=reference>
URL preview
A url: https://example.com
<a class=link-preview> with title, description and image
Images
Put the image file in your project and link to it like any image:

The text in the brackets is the image's alt text: what a screen reader reads, and what shows if the image can't load. Describe what the image shows.
A path without a leading / is relative to the page, as a browser would read it: keyboard.jpg is beside the page, and ../keyboard.jpg is a folder up. A path with a leading / is from the root of the site.
Text on the same line, after the image, is its caption:
 The keyboard I wrote this on.
The image and its caption become a <figure class=image> with a <figcaption>.
Vowel resizes JPEG and PNG images to several widths and formats, so each browser downloads the smallest one that fits (see Files).
Images hosted on an image CDN, such as Imgix or Cloudinary, get the same responsive <picture> element, built from the CDN's own resizing URLs. Nothing is downloaded. Vowel recognises the CDNs that the unpic library supports; an image from anywhere else is left as a plain <img>.

Links
Vowel has four ways to point to other pages:
- Relative paths:
./example-file-path.md - Glob paths:
./example-folder/** - Page paths:
/example-page-path - Wikilinks:
[[Example Page Name]]
A link to a page or file on your site that doesn't exist is reported as a warning in the terminal, naming the page it's on. The link is left as written.
A page that other pages link to gets a "linked from" list. A link counts when it is written explicitly:
- a markdown link to a page, in any of the spellings above, or a wikilink
- a page reference on its own line (see Glob paths)
- a frontmatter value that is a link, such as
related: ./other.md
Listings, external links and links to a section of the same page don't count.
Relative paths
A link to a file, relative to the page it's on, resolves to that file's published page:
Read more in the [blog post](./blog/announcement.md). Or, check the [documentation](../documentation.md).
./announcement.md, announcement.md and ../announcement.md all work. A #section on the end links to that heading on the page: ./announcement.md#details is /announcement#heading_details, since every heading's id starts with heading_. A link to a heading on the same page, [details](#details), works the same way.
A link without a file extension, such as about or ../tags/design, is read as a URL, the way a browser would read it from the page it's on.
Relative paths to secret pages must include their salt (./secret-announcement##rubber-hammer.md).
A relative path alone in a paragraph will render a thumbnail of the target page:
./announcement.md
Glob paths
A path on a line by itself embeds or lists pages.
/blog/first-post a card for one page
/blog/* every page in /blog
/blog/** every page in /blog and its subfolders
Listings are newest first. Add a query string to narrow one:
Parameter
Effect
count=5
Show at most five pages
tag=design
Only pages tagged #design
view=table
A table instead of cards
properties=title,date,status
The table's columns, in order
/blog/**?count=5&tag=design
/projects/*?view=table&properties=title,client,year
A table column can be any page property, including frontmatter keys Vowel doesn't use itself.
A listing written with an absolute path lists published pages and never shows a secret one. A listing written as a relative source path, like ./members##autumn-glaze/*, can list a secret folder; the page it appears on shows the hashed URLs. An absolute path containing ## shows nothing, so a salt never reaches the page by accident.
Page paths
Published URLs are absolute paths, so you can link to them as you would link to any URL on your website.
See my [about page](/about).
A page path alone in a paragraph will render a thumbnail of the page:
/about
Wikilinks
A wikilink finds a page by its file name, without the extension and ignoring case: [[Hello World]] finds hello world.md or Hello World.md, wherever it is. It doesn't find hello-world.md. A page can list other names it answers to under its aliases frontmatter property.
Override wikilink anchor text with a bar:
[[Example Page|example override text]]
Link to a section with a hash symbol:
[[Example Page#Example heading]]
To avoid name collisions, scope the link to a folder:
[[Example Folder/Example Page]]
If several pages have the same name, Vowel chooses the nearest one: the same folder, then the folder sharing the most of its path, then the shortest path, then alphabetical.
If a wikilink has no match, Vowel renders an <a> tag with no href, and reports it as a warning in the terminal.
URL thumbnails
Just as you might render a thumbnail of a page on your website with a path, you can render a thumbnail of an external webpage by putting a URL alone in a paragraph, prepended with http:// or https://:
https://example.com
The thumbnail may take a moment to load while Vowel fetches the URL. If Vowel fails to fetch the URL, the bare URL will render on the page. Vowel will attempt to refetch the URL later and update the thumbnail if it succeeds.
This data is cached in a $links/ folder in your project.
Tags
A #hashtag anywhere in the text tags the page and links to the tag's page:
Notes from the conference. #design #events
Tags can also go in the frontmatter, and are added to the hashtags in the text:
tags: [design, events]
A hashtag starts at the beginning of a line or after a space, and runs on through letters, digits, underscores, hyphens and slashes. Only ASCII letters count, so #café is the tag caf.
Every tag gets a page at /tags/<tag> listing its pages, and /tags lists every tag. The pages exist only while some page uses the tag. A slash makes a nested tag: #science/physics has the page /tags/science/physics, and /tags/science lists the tags beneath it. A page tagged #science/physics is not listed under #science.
List a tag's pages anywhere with a glob path: /blog/**?tag=design.
Emoji
Vowel replaces :name: with its emoji character, using the names from emojilib: :tada: is 🎉. An unknown name is left as written.
Icons
:folder/name:, with a slash, is an SVG from your project: :icons/github: shows icons/github.svg. The <img> carries the file's URL as --url-icon, so your CSS can colour a one-colour icon like text (see Files). If the file doesn't exist, the shortcode is left as written.
Alerts
A blockquote that starts with [!TYPE] is an alert:
> [!WARNING]
> Vowel is in active development.
The rest of the first line is the alert's title. Without one, the title is the type, written as a word: "Warning".
> [!NOTE] How to render
> Lorem ipsum.
The type is the alert's class: [!WARNING] is alert warning, and any word works, so [!CARD] is alert card.
Code
A fenced code block with a language is syntax-highlighted when the page is built, using Prism languages. A markdown or md block is highlighted the way Vowel reads it, with its frontmatter, wikilinks, hashtags, alerts and listings. The highlighting stylesheet is only linked from pages that have code. A block without a language, or with one Prism doesn't know, is left plain.
The code is marked with Prism's classes, such as token keyword, and the block's <pre> and <code> have its language as a class, such as language-js, so a Prism theme can style them. Your styles.css overrides Vowel's highlighting colours.
```js
const greeting = "hello"
```
A long line scrolls sideways, except in a markdown or md block, which wraps like prose.
A code block can have a title, such as its file name, in quotes after the language. title="..." works too. The block is then a <figure class=code>, with the title as its <figcaption>. GitHub shows a titled block without its title.
```mdLorem ipsum
```
Metadata
Vowel attempts to read metadata directly from a file's markdown, so many pages have no need for YAML frontmatter.
# Hello world
May 28, 2026

Today is the first day of the rest of my blog.
| Property | Inferred from |
|---|---|
title
| A # heading on the first line. Without one, the filename.
|
date
| A line that is only a date, near the top. Without one, a date in the file's path. |
image
| An image on its own line, or with its caption after it, near the top. A captioned image is rendered with its caption. |
description
| A paragraph followed by a horizontal rule, near the top. Without one, the first paragraph that isn't one of the above. |
breadcrumb
| The title |
tags
| Every #hashtag in the text, added to any tags: in the frontmatter
|
A title taken from a filename keeps the filename's own capitals: Hello World.md is "Hello World". A name in lowercase becomes a sentence, its hyphens and underscores read as spaces: hello-world.md is "Hello world". Folders and tags are named the same way. To choose the title yourself, start the page with a # heading.
"Near the top" means among the first blocks after the title, before the first ordinary paragraph. A line only counts when its property isn't already set: with a date: in the frontmatter, a date line is ordinary text, and so is a second date line. Vowel stops reading metadata at the first ordinary block.
Metadata written in the text is rendered with the page's metadata, directly inside <main> and ahead of the content, like its frontmatter equivalent. Your file isn't changed. A property from the frontmatter carries its key as a class (<time class=fm_date>); one from the text doesn't.
Only the first # heading is the title. Any other # heading becomes an h2.
Dates
A date on its own line near the top of a page becomes the page's date, rendered as a <time> element in your own wording. A date line must be the whole line: May 28, 2026, 28 May 2026, 2026-05-28 and 05/28/2026 all work, but Published May 28, 2026 and **May 28, 2026** are prose.
A page with no date in its frontmatter or text takes one from its path, if the path has one:
Path
Date
blog/2024-05-06.md
May 6, 2024
blog/2024-05-06-trip.md
May 6, 2024
blog/2023/04/07/hello-world.md
April 7, 2023
journal/2024/april/12.md
April 12, 2024
blog/2024-05-06/entry.md
none: a folder named like a date isn't one
projects/2024/orrery.md
none: a year alone isn't a date
A date shapes how a page is treated. Dated pages are posts: they appear in the feed (when the site has a domain) and are left out of the navigation menus. Undated pages are the site's structure: they appear in the menus.
Description
The description is used in meta tags, cards and the feed. To choose it in the text, write one paragraph near the top and end it with a horizontal rule:
# Hello world
May 28, 2026
A short summary of the post, for cards and search results.
---
The post itself starts here.
The paragraph is rendered as the page's description, and the rule as nothing. Leave a blank line before the ---: a line of text directly above --- is a heading in markdown. *** is also a horizontal rule, and never makes a heading.
Without a rule, the description is the first ordinary paragraph. A description: in the frontmatter overrides both.
Contents
If a page has more than one heading, Vowel will build a table of contents and render it as <nav aria-label="Contents"> in the <main> element.
Each heading gets an id from its text, so ## Getting started can be linked as #getting-started.
Frontmatter
Frontmatter is metadata about a file that is stored in a block of YAML at the top of a markdown file.
---
title: Hello, world
date: 2026-05-28
description: The first post.
---
The YAML is demarcated by two horizontal rules (---).
Properties defined in frontmatter will override any inferred properties.
Key
Type
Meaning
title
text
Page title
date
date
Publication date; makes the page a post
description
text
Meta description, for meta tags, cards and the feed
slogan
text
Shown under the title, and at the end of the page's <title>. The homepage's is the site's hero. Also the description, if there is no other.
image
path
Meta image, for meta tags and cards
styles
paths
Stylesheets for this page alone (see [[Design#CSS
breadcrumb
text
Label in navs. For a section's index page, the section's label everywhere.
tags
list
Hashtags for organization
author
text
Post author for its feed entry
aliases
list
Other names for wikilinking
atproto_lexicon
text
Publish this page as a record of this lexicon (see [[Site#AT Protocol
Paths are URL paths from the root of the site: image: photo.jpg and image: /photo.jpg both mean /photo.jpg. Use ./photo.jpg for a relative path.
Any other key is kept as written. It is shown on the page, and can be a column in a table listing.
A value of the wrong type is logged and corrected where it can be (title: [a, b] becomes a, b) or dropped where it can't (date: Thursday).
If Vowel fails to parse the frontmatter, it will treat the YAML as regular markdown content.
status tells Vowel how to handle a page.
Status
The page
published
Write and list. Default
hidden
Write, but do not list.
draft
Do not write, do not list.
deleted
Do not write, do not list, and destroy AT Protocol record.
Pages are reactive, so one that changes from published to draft will disappear from the website output.
Any other value will be treated as generic frontmatter and listed at the top of the page.
Property
Behavior
html_file
false writes no file for the page. It has no URL, but it is still listed wherever that needs no link: a card, a table row, the feed. Menus and the sitemap leave it out.
markdown_mirror
true publishes the page as markdown too, and false doesn't, whatever the root settings.md says (see [[Site#Markdown mirrors
sitemap_item
false leaves the page out of sitemap.xml
rss_item
false leaves the page out of feed.xml
global_nav_item
false leaves a top-level page out of the site menu
local_nav_item
false leaves the page out of its section's menu