Configuration

One config.kdl at the project root, in KDL. Every key has a default, so you only write what you want to change.

site "My Site"
url "https://example.com"
author "Ada"
lang "en"

paths {
  content "content"
  dist "public"
}

links {
  style "clean"
}

generate {
  sitemap #true
  feed {
    formats "rss" "atom"
    limit 20
  }
}

A one-line config.kdl holding site "My Site" is a valid site. --config points at a file somewhere else, --root at a different project directory.

KDL in one minute

// a line comment
prune #true                 // booleans are #true and #false
serve { port 1821 }         // a block groups keys under a name
links { style clean }       // a simple word needs no quotes
hooks {
  before #"tailwindcss -i "assets/_app.css" -o "assets/style.css""#
}

Booleans are #true and #false. A bare word parses as a string, so style clean and style "clean" are the same; quote anything with spaces, slashes, or punctuation. A raw string #"..."# keeps inner quotes intact, which is what a hook command usually needs, and """ opens a multi-line one.

The shape of the tree

The top level is grouped by concern. Each block answers one question, and the page that answers it in full is on the right.

Every key, with its value shape and what it does, is in the config reference. baudelaire reference assets.images prints one subtree of the same thing in the terminal.

The enclosing block is what gives a name its meaning. paths { assets } is the directory your stylesheets are read from; the top-level assets block is the pipeline that processes them. Same word, different question, never the same scope.

A block’s presence is the switch

Writing the block turns the feature on, and a block with nothing to configure can be written bare:

generate {
  llms
  robots {
    disallow "/drafts/"
  }
}

That writes both llms.txt and robots.txt. Delete the node and neither is written.

Turning one back off

Deleting the node is not always available. A profile and a theme’s theme.kdl both overlay nodes onto a base, so they can set a key but never remove one, and naming the block is exactly what turns it on. Every block of this kind takes #false on its own line:

profiles {
  fast {
    check #false
    artifacts {
      cards #false
      pdf { pages #false }
    }
  }
}

#true is accepted too, and means what presence already meant.

One block is not switchable this way: artifacts { bundles } is on whenever it names a target, so naming none is already how it is off.

Some blocks have a setting decided before you write anything, so they carry a bare flag rather than a presence switch, in whichever polarity the default calls for:

content {
  markdown #false   // `.md` files are pages by default; stop reading them
  drafts #true      // drafts are skipped by default; build them
}

Each is shorthand for the block’s own flag key, and the two keys differ: markdown #false is markdown { enabled #false }, drafts #true is drafts { build #true }. Write the long form when the block configures something else too.

Commenting a block out

/- in front of any node comments it out whole, settings intact:

generate {
  sitemap #true

  /-search {
    index "terms"
    snippet 240
  }
}

Search is off, and turning it back on is deleting two characters. This composes with presence-as-a-switch: /-llms is how you keep the llms { } block you tuned without emitting the file.

Hosting under a subdirectory

Give url a path and the whole site is served from it:

url "https://user.github.io/project"

Links, assets, redirects and the search client all resolve under /project, and the absolute URLs in the sitemap, feeds and canonical tags carry it. Only the emitted URLs shift. The files on disk keep their plain layout (public/blog/index.html, never public/project/blog/index.html), so the host maps the path back for you. baudelaire serve previews under the same path, and --base-url overrides it for one build.

Typos are errors

The parser knows every valid key, so a misspelling fails the build instead of silently doing nothing:

unknown config key `prety`
  help: did you mean `pretty`?
        valid keys: `pretty`, `embed`, `meta`, `anchors`, ...

The suggestion is scoped to the block you are in, so a real key written at the wrong level is caught too.