Vowel processes images, fonts, videos, documents, and data for web serving.
- Content: MD
- Image: JPEG, PNG, WebP, GIF, AVIF
- Graphic: SVG, ICO
- Font: WOFF, WOFF2, TTF, OTF
- Video: MP4, WEBM
- Styles: CSS
- Data: CSV, JSON
- Documents: PDF
Vowel will either copy these files directly or else perform useful transformations, depending on the file type.
Vowel will ignore all other file types.
Content
In Vowel, a file is a website page and a folder is a website section. Every page exists in a section, and every section has an index page, which can be user-defined or generated automatically.
Learn more about how to write markdown in Markdown.
Homepage
The homepage is home.md.
404 page
Most website hosts recognize /404.html as the website's error page. Vowel automatically generates this file, but you can override it with your own 404.md file. It is left out of every nav, page list, sitemap and feed.
Automatic pages
Vowel creates some pages automatically if they don't already exist:
Page
When
/index.html
Without a home.md
/<folder>.html
For each folder with pages, without a <folder>.md beside it
/404.html
Without a 404.md
/tags.html, /tags/<tag>.html
While any page has a hashtag
You can override all of these pages: a file of your own at the same path replaces the generated one.
Page routing
Vowel converts file paths to URL-friendly paths. For instance, blog/First Post.md will become /blog/first-post.html. Paths are lowercased and special characters are converted to hyphens.
The homepage is the exception, at /index.html, from home.md, and so are secret pages, whose paths are hashed (see below).
Secret pages
Sometimes, you want to discretely publish something on your website. This is what secret pages are for.
A secret page has a hashed file path, which looks like this:
https://example.com/84e75a6994e5a6c9.html
A hash is a semi-random string of numbers and letters. Vowel generates the hash from the file name. However, on its own, a hashed file name is not really secret. For instance, if your file name is secret.md, the hashed file path might be 58e16dd393e7c6db.html. But that hash isn't really secret. Anyone who suspects that you have a file called secret.md could generate the exact same hash and find your page. To generate a hash that is harder to guess, we add a salt — some random text. To define a salt, append ## to your filename, followed by some random text, like secret##purple-banana.md. If a file path has a salt in it, Vowel will hash the path and hide the file.
This works for folders, too. You could have secret##purple-banana/psst.md. Vowel will hash the folder path, hiding everything inside, including images and stylesheets.
Secret pages are left out of the sitemap, the feed, the navs and every page list. The one way to list them is a relative glob path that names the secret folder, salt and all, such as ./secret##purple-banana/*.
A markdown link to a secret page must include the salt: ./secret##purple-banana/psst.md. A wikilink finds it by name, like any other page: [[psst]].
Want to change a page's hash? Just change the salt. secret##orange-avocado.md will be republished under a new path.
Every build logs the URL of each secret page, which is the only way to find it aside from looking at the HTML output. That includes the preview, deploy and publish, and so a build in CI.
Remember, anyone with the link can read the content. If a website scraper finds the link somewhere, it could appear in AI chats or search results.
Ignored files
Vowel generates one page for (almost) every folder and markdown file in your project, with a few exceptions:
- A file with
status: draftset in its frontmatter will have no effect settings.mddeclares folder settings, so it does not emit its own HTMLAGENTS.mdis notes for AI agents working in the folder, so it is not a page- Files and folders prefixed with a
$are virtual, so other files may reference them but they will not emit their own HTML - Folders that contain no published markdown will not emit a page
- Common technical files and folders, such as hidden files and
node_modules, are ignored altogether
Images
After written content, images are the most important files in a website, and Vowel treats them as such.
Vowel optimizes JPEG and PNG images, resizing them to several widths and converting them to modern formats for serving. Vowel also reads every image to inject useful metadata into the image's HTML.
Place full-sized images into your project folder and reference them normally in your markdown:

Vowel renders a <picture> element to serve the image at various sizes and formats. For convenience, the <picture> carries the image's dominant colour as --color-image-dominant, and, for an image without transparency, a tiny WebP placeholder as --url-image-placeholder. A page's own image also puts its dominant colour on the page's <main>, and on the page's <article> in a listing, so anything beside the image can use it, such as text that contrasts with it.
Each <img> element has width and height properties to prevent layout shifts.
Vowel never publishes a JPEG or PNG at its full size. Wherever a page names one as a single file, such as a logo, an icon, a link preview's og:image or a link to the image, Vowel links one of its resized copies instead. The one exception is a favicon.png at the root of the project, which Vowel publishes as it is.
WebP, GIF and AVIF images are published and shown as a plain <img>.
Graphics
Vowel copies SVGs directly. In HTML, Vowel also applies a --url-logo variable to the logo's <img> element, and --url-icon to an icon's, which enables dynamic coloring. Rather than rendering the SVG directly, hide the SVG, set a background color, and mask the element with the URL:
img#logo {
object-position: -100vmax;
background: red;
mask-image: var(--url-logo);
}
object-position moves the image's own pixels out of its box, so only the background shows, in the shape of the mask.
ICO, which are primarily used for favicons, get copied straight through. See Site for info on using favicons.
Styles
Vowel uses LightningCSS to prefix and minify CSS and then copies it through to your website.
Vowel will also link CSS in your HTML for you. A styles.css file automatically gets applied to everything in the same folder and subfolders. In a folder's settings.md, or in a page's frontmatter, you can specify stylesheets with other names:
---
styles:
- ./blog.css
---
Vowel will also conditionally inject theme stylesheets. All styles in theme stylesheets get wrapped in CSS layers, which zeros their specificity relative to higher layers. That means any styles you write yourself will override theme styles.
Fonts
Font files get copied through directly. To use them in your CSS, write a @font-face rule in your stylesheet:
@font-face {
font-family: 'Example Font Name';
src: url(example-font-file.woff2) format('woff2');
}
Vowel handles .woff, .woff2, .ttf and .otf files.
Other files
These are copied as they are, for linking or embedding:
- video:
.mp4,.webm - data:
.csv,.json - documents:
.pdf - favicons:
.ico
A file over 25 MiB is not published, and the build logs an error naming it. That is the largest file Cloudflare Pages accepts. Host large video elsewhere.