# Markdown

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

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           | `![alt](photo.jpg)`                                                  | `<picture>`: AVIF, WebP and the original at four widths, with its size and a placeholder       |
| Image caption   | `![alt](photo.jpg) 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:

```markdown
![A keyboard on a desk](keyboard.jpg)
```

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:

```markdown
![A keyboard on a desk](keyboard.jpg) 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](https://vowel.cc/docs/guides/files#heading_images)).

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](https://unpic.pics/) library supports; an image from anywhere else is left as a plain `<img>`.

```markdown
![Airport](https://littlefair.imgix.net/cdg.jpeg)
```

## 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](https://vowel.cc/docs/guides/markdown#heading_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:

```markdown
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](https://vowel.cc/docs/guides/files#heading_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.

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

```markdown
Notes from the conference. #design #events
```

Tags can also go in the frontmatter, and are added to the hashtags in the text:

```yaml
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](https://vowel.cc/docs/guides/markdown#heading_glob-paths): `/blog/**?tag=design`.

## Emoji

Vowel replaces `:name:` with its emoji character, using the names from [emojilib](https://github.com/muan/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](https://vowel.cc/docs/guides/files#heading_graphics)). If the file doesn't exist, the shortcode is left as written.

## Alerts

A blockquote that starts with `[!TYPE]` is an alert:

```markdown
> [!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".

```markdown
> [!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](https://prismjs.com/) 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.

````markdown
```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.

````markdown
```md "Hello World.md" Lorem ipsum ```
````

## Metadata

Vowel attempts to read metadata directly from a file's markdown, so many pages have no need for YAML frontmatter.

```markdown
# Hello world May 28, 2026 ![Keyboard](keyboard.jpg) 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:

```markdown
# 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.

```yaml
--- 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](https://vowel.cc/docs/guides/markdown#heading_tags) for organization                                                               |
| `author`          | text  | Post author for its feed entry                                                                                                                |
| `aliases`         | list  | Other names for [wikilinking](https://vowel.cc/docs/guides/markdown#heading_wikilinks)                                                        |
| `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](https://vowel.cc/docs/guides/markdown#heading_glob-paths).

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                                                                                                                          |
