# Files

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

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

> [!WARNING]
> Secret pages are discrete, but they are not actually private or secure. Anyone who can see your files, or a log of a build, can find them. Do not use them to share sensitive information.

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: draft` set in its frontmatter will have no effect
- `settings.md` declares folder settings, so it does not emit its own HTML
- `AGENTS.md` is 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:

```markdown
![Keyboard](keyboard.jpg)
```

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.

> [!NOTE]
> To learn how to insert images, write alt text, and add captions, see [Markdown](https://vowel.cc/docs/guides/markdown#heading_images).

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:

```css
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](https://vowel.cc/docs/guides/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:

```markdown
--- styles: - ./blog.css ---
```

Vowel will also conditionally inject theme stylesheets. All styles in theme stylesheets get wrapped in [CSS layers](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@layer), 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:

```css
@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.
