Skip to content HtmlpressStatic site generator HtmlpressStatic site generator

Change theme

Keyboard shortcuts

Frontmatter

Updated

A page's metadata is a set of keys, the same in both formats. A Markdown page writes them as its YAML frontmatter; an HTML page 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. 

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

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.
label the title A shorter name for the page's navigation entry.
icon none A built-in icon 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.

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.

Overriding without editing

Every field here can also be set from htmlpress.yaml, without touching the file; see Article Patches.

See also

Created with ❤ and Htmlpress

Actions

Edit on GitHubView as Markdown

Contents