# Frontmatter

> The keys that set a page's title, description, image, order and layout, as Markdown frontmatter or HTML head tags.

A page's metadata is a set of keys, the same in both formats. A [Markdown page](/authoring/markdown-pages/) writes them as its YAML frontmatter; an [HTML page](/authoring/html-pages/) as its `<head>`, `title` as `<title>` and every other key as `<meta name="key" content="…">`. A page is a full document or a fragment, and htmlpress reads both the same way. Every key is optional; htmlpress derives sensible defaults from the file when one is missing.

**HTML**

```html
<title>Getting started</title>
<meta name="description" content="Install and run it.">
<meta name="order" content="1">

<h1>Getting started</h1>
<p>Plain HTML, styled by the theme.</p>
```

**Markdown**

```md
---
title: Getting started
description: Install and run it.
order: 1
---

# Getting started

Plain Markdown, styled by the theme.
```

The body becomes the page's content inside the layout. Give every page a `title` and one top-level heading.

## Article metadata

Identity and presentation of the page.

| Key           | Default                             | Purpose                                                                                                                                                                                                           |
| ------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`       | first `<h1>`, else the file name    | Names the page in the navigation and the browser tab.                                                                                                                                                             |
| `description` | `description` from `htmlpress.yaml` | The page's description for search engines and social previews.                                                                                                                                                    |
| `image`       | none                                | The image shown when the page is shared, as `og:image`. A relative URL is resolved from the page's source file; a local one needs `site` to be made absolute, and is left out without it.                         |
| `head`        | none                                | Markdown only: raw HTML added to the layout's head, after the theme. An HTML page writes its own `<link>`, `<style>` or `<script>` in its `<head>`, or before its first content, and they are added the same way. |
| `date`        | none                                | When the page was published, `YYYY-MM-DD` (a timestamp is cut to its date; anything else is an error). Shown under the title, and it sorts a blog.                                                                |
| `author`      | none                                | An author shown under the title; a list, or the tag repeated, for several.                                                                                                                                        |
| `keywords`    | none                                | Tags, a list or comma-separated; in a blog each gets a page listing its posts.                                                                                                                                    |

The line under the page's `<h1>` also says when its file last changed, from `git log`, when the project is in a git repository; the same date is the page's `<lastmod>` in `sitemap.xml`.

## Sidebar settings

How the page shows up in the navigation.

| Key           | Default                            | Purpose                                                                                                                                                                                                                                               |
| ------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order`       | none (sorted by path)              | An integer sort position; see "Ordering rules" below.                                                                                                                                                                                                 |
| `layout`      | the site's layout                  | Wraps the page in `.htmlpress/layouts/<name>.html` instead, for a page that wants different chrome, such as a landing page without the sidebar. A missing layout fails the build; see [Overriding and Escaping](/customization/overriding-escaping/). |
| `label`       | the title                          | A shorter name for the page's navigation entry.                                                                                                                                                                                                       |
| `icon`        | none                               | A [built-in icon](/authoring/rich-elements/#icons) before a top-level navigation entry, or a folder's group for its index page; pages inside a folder show none. An unknown name fails the build.                                                     |
| `sidebar`     | `true`                             | `false` leaves the page out of the navigation and the previous and next links; it is still built and reachable by its URL.                                                                                                                            |
| `toc`         | `true`                             | `false` turns off the page's table of contents.                                                                                                                                                                                                       |
| `breadcrumbs` | the config's `breadcrumbs`         | `false` hides the trail of folders above the content; `true` shows it even when the config turns it off.                                                                                                                                              |
| `source-url`  | `edit` followed by the page's path | Where the page's source link leads, for a page whose source lives elsewhere; `source-action` set to `view` labels it "View on GitHub" instead of "Edit on GitHub".                                                                                    |

### Ordering rules

- The root `index.html` always leads.
- Pages with an `order` of 0 or more come next, ascending.
- Pages without one follow, by path.
- Pages with a negative `order` come last, so `-1` pins a page to the very end and `-2` sits just before it.

The order places a page among its siblings: pages nest under their folder's `index.html`, and a folder sits where that page's `order` puts it, or, when it sets none, where its first page would.

An `order` that is not an integer fails the build. A `404.html` at the root is the page a host shows for a missing URL; it is left out of the navigation, and a project without one gets a built-in "Page not found".

## URL

A page is served at a folder named after its file, `guides/build.html` at `/guides/build/`, and `index.html` at its own folder: `guides/index.html` at `/guides/`, every name slugified. See [Links](/authoring/links/).

`path: /start/` serves the page at another URL, independent of its file path: a path ending in `/` names that folder, and one ending in `.html` the page that file would be, so `/start.html` serves it at `/start/` too. Two pages on one URL fail the build.

On a site with `languages`, a file named `guide.es.html`, or one with `language: es`, is the Spanish translation of `guide.html`, served at `/es/guide/`; see [Translations](/customization/translations/).

## Overriding without editing

Every field here can also be set from `htmlpress.yaml`, without touching the file; see [Article Patches](/customization/article-patches/).

## See also

- [Article Sections](/customization/article-sections/) — how folders group pages in the navigation.
- [Article Patches](/customization/article-patches/) — set page metadata from config.