Braised Docs

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.

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.

description

Sets the page description used in <meta name="description"> and social preview tags (Open Graph, Twitter Card). When absent, braised falls back to the first paragraph of the page body — so most pages get useful previews automatically.

---
title: API Reference
description: Complete reference for the braised HTTP API.
---

The resolved value (explicit or auto-derived) is available to templates as .Page.Description. It is also present in .Page.Meta as "description" when explicitly set in frontmatter, but prefer .Page.Description in custom templates — it includes the fallback.

For agent-facing outputs (llms.txt, frontmatter-index), see llm_description: below.

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. Use this for HTML <meta> tags and other template-layer signals that braised doesn't manage as first-class fields.

Social preview image:

description: and core Open Graph/Twitter tags are handled automatically — see description: above. Add og_image: when you want a per-page image in social unfurls:

---
title: API Reference
og_image: /assets/api-og.png
---

{{if index .Page.Meta "og_image"}}
<meta property="og:image" content="{{index .Page.Meta "og_image"}}">
{{end}}

Add this to a head partial override (see Layouts and Partials).

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 will still appear in sitemap.xml — the sitemap only respects llm_exclude. To suppress a page from both HTML meta and all braised outputs, set both noindex: true and llm_exclude: true.

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.