On this page

Front matter

A page may open with a front-matter block: three hyphens, a run of key: value lines, three hyphens.

---
title: Connecting to the device
description: Pair over Bluetooth, join a network, and reach the web interface.
order: 2
---

# Connecting to the device

...

Front matter is optional. A page without it works fine — the title comes from its first heading.

Recognized keys

Key	Type	Effect
`title`	string	Page title. Used in the sidebar, the browser title, the table of contents rail heading, prev/next links, `llms.txt`, and search results.
`description`	string	Meta description, Open Graph and Twitter description, and the summary line in `llms.txt`.
`order`	number	Sort position within its navigation section. Lower sorts first.
`slug`	string	Parsed and stored, but it does not change the URL. The URL always comes from the file path.

Any other key is parsed away and ignored. There is no error for an unrecognized key.

Fallbacks

Neither title nor description is required.

Title resolves in this order:

front-matter title
the first # heading in the body
the literal string Untitled

A page called Untitled in your sidebar means a file with no front-matter title and no # heading.

Description resolves in this order:

front-matter description
the text of the first paragraph, stripped of tags and clamped to 155 characters on a word boundary with a trailing ellipsis
the site name plus "documentation", substituted at render time when both are empty

The automatic fallback is usually acceptable and occasionally embarrassing — if your first paragraph is "See the table below," that is your search-result snippet. Write a description on any page you care about.

Ordering

order sets the sort key within a navigation section. Entries sort by order ascending, then alphabetically by title as a tie-break. The default is 0, so a folder where nothing declares an order sorts alphabetically.

---
title: Installation
order: 1
---

Ordering is per-section, not global. A section's own order positions the section among its siblings; the order of the pages inside it positions them among each other. See Folders and navigation.

Parser limitations

The parser is deliberately small, and it is not YAML.

Flat key-value only. Nested maps, lists, and multi-line values are not parsed. tags: followed by indented - one lines is ignored, not an error.
One line per key. The value is everything after the first colon on that line.
Quotes are stripped at the ends only. A single leading and trailing ' or " is removed. Quoting is never required — a value containing a colon is fine unquoted, because only the first colon splits the line.
Keys must start with a letter or underscore and may contain word characters and hyphens.
The opening fence must be the first thing in the file. A blank line or a byte-order mark before --- means the block is treated as body content.
order is coerced with Number(). A non-numeric value becomes NaN, which sorts unpredictably. Keep it an integer.

If a closing --- is never found, the whole file is treated as body content and the front matter appears as text on the page. That is the usual cause of a page whose first line reads title: Something.

PreviousMarkdown reference NextFolders and navigation