Frontmatter

Frontmatter is a YAML block at the top of a Markdown file, delimited by ---. It controls page-level metadata. title is required — all other fields are optional.

---
title: Installing the Binary
nav_title: Installation
draft: true
id: installation-guide
layout: blank
hide_aside: false
---

Fields

title

Required. The page title used in the browser tab, the <h1> heading rendered by the page template, and nav label fallback. Missing title is a build error — the page is skipped.

---
title: Installing the Binary
---

Body content should start at ##. The page template owns the <h1> — do not put a # Heading at the top of your Markdown body.

draft

When true, the page is excluded from the build unless build.drafts: true is set in braised.yaml. Draft pages are also excluded from link validation — links to them are correctly reported as broken.

---
draft: true
---

id

Every page automatically gets a braised:ref/ label derived from its URL — no frontmatter needed. A page at /getting-started/installation/ is reachable as braised:ref/getting-started/installation from any other page.

id: adds a sibling label alongside the URL-derived one, typically a shorter or more memorable name:

---
id: installation-guide
---

Both labels resolve to the same page:

[installation](braised:ref/getting-started/installation)   ← always available
[installation guide](braised:ref/installation-guide)       ← only when id: is set

IDs must be unique across the site. Duplicates produce a build warning; the first definition wins. See Links and Cross-References for full details.

nav_title

A shorter label for the sidebar navigation entry. When set, this value replaces the full title in the nav column only — the page <h1> and browser tab still use title.

---
title: Installing from Source on Linux and macOS
nav_title: Install from Source
---

Use nav_title when the full title is too long for the sidebar column.

hide_aside

When true, suppresses the right-hand table-of-contents aside, giving the content column the full page width. Useful for landing pages, index pages, and pages with few or no headings.

---
hide_aside: true
---

layout

Specifies a non-default page layout. Braised looks for layouts/{name}.html in your project first, then falls back to the built-in layout with that name. An unknown layout name is a build error — the page is skipped.

---
layout: blank
---

Built-in layouts:

Name	Description
page	Default: header, sidebar, content, TOC aside, footer
blank	Full-width: header, content, footer. No sidebar or TOC. Use for landing pages.
reference	Man-page-style: header, sidebar, content, TOC aside, footer. H2 sections ruled. Use for API or command reference pages.

aliases

A list of additional cross-reference IDs for this page. Each alias is registered in the ref index alongside the primary id, allowing multiple stable identifiers to point to the same page.

---
id: installation-guide
aliases:
  - install
  - setup-guide
---

Any of these can then be used as a link target:

See the [setup guide](braised:ref/install) for prerequisites.

Aliases follow the same uniqueness rules as id — a duplicate alias (across any page's id or aliases) produces a build warning and the first registration wins.

llm_description

Overrides the description used in llms.txt and the frontmatter-index artifact for this page.

---
title: Theme Variables
llm_description: Complete reference for all CSS custom properties and their defaults.
---

When absent, braised falls back to description: frontmatter, then the first paragraph of the page body.

See Authoring for Agents for the full resolution order and how this interacts with llms.txt and the MCP tools.

llm_exclude

When true, excludes the page from all agent-facing outputs — but the page is still built to dist/ and accessible by direct URL.

---
title: Internal Notes
llm_exclude: true
---

See Authoring for Agents for the full exclusion policy.

Custom metadata

Any frontmatter key not listed above is collected as page metadata and exposed to templates as Page.Meta. The primary use case is injecting standard HTML <meta> tags — search descriptions, Open Graph tags, crawler directives — that braised doesn't manage natively.

Search description and Open Graph:

---
title: API Reference
description: Complete reference for the braised HTTP API.
og_image: /assets/api-og.png
---

In a partial override for the head block (see Layouts and Partials):

{{define "head"}}
{{if index .Page.Meta "description"}}
<meta name="description" content="{{index .Page.Meta "description"}}">
<meta property="og:description" content="{{index .Page.Meta "description"}}">
{{end}}
{{if index .Page.Meta "og_image"}}
<meta property="og:image" content="{{index .Page.Meta "og_image"}}">
{{end}}
<meta property="og:title" content="{{.Page.Title}}">
<meta property="og:type" content="website">
{{end}}

Crawler control:

---
title: Internal Staging Notes
noindex: true
---

{{if index .Page.Meta "noindex"}}
<meta name="robots" content="noindex,nofollow">
{{end}}

Limitation: custom metadata stays in the template layer. It does not affect the sitemap, llms.txt, or artifacts. A page with noindex: true in frontmatter will still appear in sitemap.xml — the sitemap only respects the first-class llm_exclude field. If you need a page excluded from both HTML meta and the sitemap, set both noindex: true (for the template) and llm_exclude: true (for braised outputs).

Custom metadata is also available in block templates via .Page.Meta.

Scope

Frontmatter has a deliberately narrow scope. It controls content metadata — never navigation order. Navigation order is owned entirely by nav.yaml.

These things are not in frontmatter:

• Page ordering or weight
• Navigation hierarchy
• Tags used for navigation grouping

This keeps content files portable and keeps navigation decisions centralised.