braised.yaml

braised.yaml is the root configuration file for a Braised Docs project. It lives at the root of your project directory alongside nav.yaml and the docs/ folder.

Full reference

site:
  title: My Documentation        # site name, appears in page titles and header
  url: https://docs.example.com  # canonical base URL, used for <link rel="canonical">
  base_url: /postgres-docs       # sub-path prefix for assets (omit for root-hosted sites)
  description: ...               # site description (meta tag)
  version: v2                    # current version label (multi-version sites)
  version_root: /docs/v2         # URL prefix for this version
  meta:                          # arbitrary site-level values for templates
    cta_url: /work-with-me/
    cta_label: Work with me
    github_url: https://github.com/example

theme: ./themes/default          # theme directory (default: themes/default)

themes:                          # named color themes (optional)
  values: [warm, neutral, dark]  # [data-theme="name"] selectors in your CSS
  default: warm                  # applied on cold load; falls back to prefers-color-scheme

versions:                        # version switcher entries (multi-version sites)
  - label: v2 (latest)
    path: /docs/v2
  - label: v1
    path: /docs/v1

build:
  output: ./dist                 # output directory (default: dist)
  drafts: false                  # include draft pages (default: false)

nav: nav.yaml                    # path to nav file, or inline nav (see nav.yaml docs)

css:
  input: theme/main.css          # path to CSS entry file (default: theme/main.css)

markup:
  goldmark:
    extensions:
      gfm: true                  # GitHub-Flavored Markdown (default: true)
      footnote: true             # footnote extension (default: true)
      attribute: false           # {#id} and {.class} on headings (default: false)
      typographer: false         # smart quotes and em/en-dash (default: false)

chunking:                        # RAG chunking settings (requires pipeline config)
  max_tokens: 512
  min_tokens: 100
  overlap: 1
  attach_code: true
  context: breadcrumb            # breadcrumb | llm | none

pipeline:                        # RAG pipeline (see Pipeline docs)
  command: python3 scripts/ingest.py   # run a script after every build
  # http: http://localhost:8000/ingest  # or POST manifest to a webhook

llms_txt:
  preamble: ""               # text inserted after > description, before first ##

artifacts:
  output_dir: artifacts/     # default: artifacts/

mcp:
  artifacts_dir: artifacts/  # default: artifacts/
  dist_dir: dist/            # default: build.output (dist)
  serve:
    host: 127.0.0.1          # default: 127.0.0.1
    port: 8081               # default: 8081

site

Field	Type	Default	Description
`title`	string	—	Site name. Appears in `<title>` as `Page Title — Site Title`.
`url`	string	—	Canonical base URL. Used for `<link rel="canonical">`.
`base_url`	string	—	Path prefix for all asset and home links. Set when the site is served from a sub-path (e.g. `/postgres-docs`). No trailing slash. See below.
`description`	string	—	Site description for meta tags.
`version`	string	—	Current version label. Used by the version switcher block.
`version_root`	string	—	URL prefix for this version's content.
`meta`	map	—	Arbitrary key/value pairs available in templates as `{{index .Site.Meta "key"}}`. Use for nav link targets, CTA copy, social URLs — anything that varies per site but shouldn't be hardcoded in the layout.

base_url

When a site is served from a sub-path rather than a domain root, CSS and JS links break because they resolve to /assets/braised.css instead of /postgres-docs/assets/braised.css. Set base_url to the sub-path prefix (no trailing slash) and the built-in layout will prefix all asset and home links automatically:

site:
  title: Postgres Docs
  base_url: /postgres-docs

Nginx example with alias:

location /postgres-docs/ {
  alias /var/www/html/postgres-docs/;
  try_files $uri $uri/ /postgres-docs/index.html;
}

base_url affects only the built-in layout's asset <link>/<script> tags and the site title home link. Page URLs in nav.yaml and cross-page links are unchanged — configure those with the correct sub-path directly. When empty (the default), all links use root-relative paths (/assets/...).

theme

Field	Type	Default	Description
`theme`	string	`themes/default`	Path to the active theme directory, relative to the project root. If the directory does not exist the theme layer is skipped. See Theming.

themes

Configures the named color themes available to the site. When absent, the built-in layout falls back to a two-state dark/light toggle driven by prefers-color-scheme.

themes:
  values: [warm, neutral, dark]
  default: warm

Field	Type	Default	Description
`values`	list of strings	—	Ordered list of theme names. Each name maps to a `[data-theme="name"]` CSS selector in your stylesheet.
`default`	string	—	Theme applied on first load when no stored preference exists. Falls back to system `prefers-color-scheme` when empty.

Templates access the theme list as .Site.Themes.Values and the default as .Site.Themes.Default. See CSS and Assets for the full theme toggle pattern.

build

Field	Type	Default	Description
`output`	string	`dist`	Directory to write HTML output. Created if it does not exist.
`drafts`	bool	`false`	When `true`, pages with `draft: true` frontmatter are included in the build.

nav

Accepts either a path to an external nav.yaml file or an inline navigation definition:

# external file
nav: nav.yaml

# inline
nav:
  - Introduction: index.md
  - Guide: getting-started/guide.md

See the nav.yaml reference for the full format.

css

Field	Type	Default	Description
`input`	string	`theme/main.css`	Path to the CSS entry file, relative to the project root.

The CSS entry file is compiled by the Tailwind v4 CLI and written to dist/assets/braised.css. See CSS and Assets for the full pipeline and customisation options.

markup

Controls Markdown rendering behaviour. All fields are optional — omitting a field preserves its default.

markup:
  goldmark:
    extensions:
      gfm: true          # GitHub-Flavored Markdown (tables, strikethrough, task lists, linkify)
      footnote: true     # [^1] footnote syntax
      attribute: false   # {#custom-id} and {.class} on headings
      typographer: false # smart quotes and em/en-dash substitution

Field	Default	Description
`gfm`	`true`	GitHub-Flavored Markdown extensions (GFM tables, strikethrough, task lists, auto-linking).
`footnote`	`true`	Footnote syntax (`[^1]`).
`attribute`	`false`	Attribute syntax (`{#id}`, `{.class}`) on headings. Matches Hugo's `markup.goldmark.extensions.extras` behaviour.
`typographer`	`false`	Smart quotes and em/en-dash substitution.

chunking

Controls the AST-based semantic chunker. Chunking requires a pipeline block — without a pipeline configured, braised skips manifest generation.

Note: The fields below are accepted by the config parser but not yet active. The chunker currently splits on headings only. Token-based grouping, overlap, and context options are planned.

Field	Type	Default	Description
`max_tokens`	int	`512`	Maximum tokens per chunk.
`min_tokens`	int	`100`	Minimum tokens before a chunk is split further.
`overlap`	int	`1`	Number of heading levels to carry over between adjacent chunks for context.
`attach_code`	bool	`true`	Attach code blocks immediately following a heading to that heading's chunk.
`context`	string	`breadcrumb`	Content prepended to each chunk for embedding context. See below.

context values

Value	Behaviour
`breadcrumb`	Prepend the nav trail (e.g. `Getting Started > Installation`) to each chunk.
`llm`	Prepend a more verbose LLM-optimised preamble describing the site and page.
`none`	No context prepended — pass the raw chunk text to the embedding model.

Environment variable substitution

Values in braised.yaml may reference environment variables using ${VAR} syntax. This is primarily useful for pipeline URLs and deployment-specific settings:

pipeline:
  http: ${INGEST_WEBHOOK_URL}

Unset variables produce a build warning and resolve to an empty string.

`llms_txt`

Controls llms.txt generation for agent audiences.

Key	Type	Default	Description
`preamble`	string	`""`	Text inserted verbatim after the `> description` line and before the first `##` section. No Markdown processing is applied.

`artifacts`

Controls the structured artifact writer.

Key	Type	Default	Description
`output_dir`	string	`artifacts/`	Directory where artifact files are written, relative to the project root.

`mcp`

Configures the MCP server (braised mcp serve).

Key	Type	Default	Description
`artifacts_dir`	string	`artifacts/`	Directory containing artifact JSON files for `braised mcp serve` to load.
`dist_dir`	string	`build.output` (usually `dist/`)	Directory containing companion `.md` files for `get_page` tool.
`serve.host`	string	`127.0.0.1`	Host address the MCP server binds to. Use `0.0.0.0` to expose on LAN.
`serve.port`	int	`8081`	Port the MCP server listens on.

`sources`

Named source registries for :::sources blocks. Each registry maps a short namespace prefix to a URL prefix, letting :::sources entries use <namespace>:path/to/file instead of full URLs.

sources:
  braised:
    label: "Braised Source"
    prefix: "https://github.com/ravindk89/braised/blob/main/"

With this config, a :::sources entry of braised:internal/config/config.go resolves to https://github.com/ravindk89/braised/blob/main/internal/config/config.go. The label is displayed as the source group heading in the rendered block.

Key	Type	Description
`<name>`	object	Registry name, used as the namespace prefix in `:::sources` blocks.
`<name>.label`	string	Display label shown as the source group heading.
`<name>.prefix`	string	URL prefix. The path after `:` in `<name>:path` is appended directly to this.

See Documentation Provenance for usage.

Minimal config

Only site.title is required. Everything else has a sensible default:

site:
  title: My Documentation