Braised Docs

Theming

Braised ships embedded defaults that produce a working site with no configuration. But because documentation often needs to match a product brand or a team's design system, theming is designed to be fully replaceable — not just tweakable.

The model is layered, working from lowest to highest priority:

  1. Braised embedded defaults — layouts, blocks, CSS, and JS bundled in the binary.
  2. Theme directory — a directory you own, often checked in as a Git submodule, that provides replacement layouts, blocks, CSS, and static assets.
  3. Site root overrides — individual files at your project root that shadow theme files one-for-one.

At each level, only the files you provide are replaced. Everything else falls through to the layer below.

Theme directory

By convention, Braised looks for a theme at themes/default/ inside your project root. You can change the path with the theme: key in braised.yaml:

theme: ./themes/my-theme

If the directory does not exist, the theme layer is skipped entirely — existing sites without a themes/ directory are unaffected.

A theme can provide any combination of the following:

themes/default/
  layouts/          ← full page layout templates
    partials/       ← partial overrides (header, sidebar, footer, toc, content)
  blocks/           ← block HTML templates
  theme/
    main.css        ← CSS entry file (processed by Tailwind)
  assets/           ← files copied verbatim to dist/assets/
  static/           ← files copied verbatim to the output root

None of these directories are required. Omit whichever your theme does not need.

How a theme is distributed

Because a theme is just a directory, the simplest distribution mechanism is a Git submodule:

git submodule add https://github.com/example/braised-theme-clean themes/default

Updating the theme is then a standard submodule update:

git submodule update --remote

You can also copy a theme directory directly into your repository if you intend to modify it.

Override granularity

Any file in your site root shadows its counterpart in the active theme. The same applies between the theme and braised's embedded defaults.

What you want to change Where to put the file
Entire page layout layouts/page.html
Just the header layouts/partials/header.html
One block template blocks/callout.html
Specific static file static/favicon.ico

The theme handles the rest. You do not need to copy anything you are not changing.

See the child pages for detailed guidance on each override type: