Your First Site

Fast path — braised init

Run braised init inside an empty directory to scaffold a working project in one step:

mkdir my-docs && cd my-docs
braised init

The wizard prompts for a site title, canonical URL, and description, then creates:

my-docs/
├── braised.yaml    ← site configuration
├── nav.yaml        ← navigation definition
├── package.json    ← Tailwind dependency
├── theme/
│   └── main.css    ← CSS entry point
└── docs/
    └── index.md    ← starter page with block examples

Install dependencies, then start the dev server:

npm install
braised serve

Open http://localhost:4321. Edit docs/index.md — the browser reloads automatically.

When you are ready to publish:

braised build
# output written to dist/

For a full description of all commands and flags, see the CLI reference.

---

Manual setup

If you prefer to set up the project files yourself:

1. Create braised.yaml

site:
  title: My Documentation
  url: https://docs.example.com

build:
  output: dist

2. Create nav.yaml

- Introduction: index.md
- Guide: guide.md

Nav entries are Label: path/to/file.md. Paths are relative to docs/.

3. Write pages

Every page requires a title in frontmatter. Body content starts at ## — the <h1> is injected by the page template from the frontmatter title.

---
title: Introduction
---

Welcome to My Documentation.

## Getting started

...

4. Set up the CSS pipeline

Create theme/main.css to import the built-in theme:

@import "braised:theme/base";
@import "braised:theme/syntax";

Add a package.json with the Tailwind dependency and run npm install:

{
  "dependencies": {
    "@tailwindcss/cli": "^4.2.2",
    "tailwindcss": "^4.2.2"
  }
}

To customise fonts, colours, or layout, see theming.

5. Build and preview

braised build

Output is written to dist/. Pages use clean URLs: guide.md becomes /guide/, served from dist/guide/index.html.

For local preview with live reload, use braised serve instead of building manually.

Build output

Output is written to dist/. A single bad page never aborts the build — all errors are collected and reported together at the end.

See Build Outputs for the full directory structure, including artifacts/ and .braised/.