Baudelaire
v0.0.17

Config reference

Every key the config accepts, in the order the parser declares them. Generated from the parser itself, so it can’t drift from what actually parses.

TIP

baudelaire reference prints this in the terminal, and baudelaire reference assets.images prints one subtree of it.
Key Shape Does
site text The site's name, used in titles, feeds and metadata.
description text What the site is, in one line, for the feed channel. Not a per-page <meta> fallback.
url url The absolute base URL. Sitemaps, feeds and social cards cannot be generated without it.
lang text The default language code, e.g. en.
author text The default author, used by any page naming none.
theme text A theme directory whose templates and assets this site layers over.
client key value .. Constants exposed to client-side JavaScript, one key value line per entry.

paths

Where the content, output and asset trees live.

Key Shape Does
content path The content tree of .typ pages.
dist path Where the built site is written.
assets path Assets that go through the pipeline: CSS, JS, images.
static path Files copied to the output verbatim, untouched by the pipeline.
templates path Where layouts and partials are imported from.
sources key value .. Files a page may take as its body, each under a name: a page names the name, never the path.

content

What the content tree holds and how it is read.

Key Shape Does
index text The filename stem that publishes at its directory's own URL, without extension.
future flag Build pages dated later than now.

content.drafts

Whether drafts are built, and how one is marked. drafts #true is drafts { build #true }.

Key Shape Does
build flag Build draft pages at all.
suffix text The filename marker that flags a draft, peeled off the stem: post.draft.typ.

content.collections

One block per collection, each named by its id.

Key Shape Does
glob text Which content files belong to this collection.
sort order | date | title What the collection's members are ordered by.
reverse flag Reverse that order.
permalink template The URL pattern its pages publish at, e.g. /{slug}/.
template text The layout its pages render through.
feed flag Also write a feed of this collection's members, beside its index.
content.collections.paginate

Generate an index over the collection. Its presence turns the index on; #false turns it off again.

Key Shape Does
size number Pages per index page. Omitted, the index is one page.
template text The layout the index renders through.
mount text Where the index publishes, if not at the collection's own path.
prefix text The path segment before a page number, as in /posts/page/2/.
content.collections.schema

What every member's frontmatter must declare, one line per field. A dict field takes a block of its own fields.

Key Shape Does
type any | str | bool | int | float | date | dict | list | list<..> | one-of<..> The shape the value must have, also writable as the leading positional: title "str". A list names what it holds: list<int>, list<dict>.
optional flag Let the field be absent. Declaring a field otherwise requires it.
default text What the page gets when it writes none, which lets the field be absent.
min number The floor the value is held to: its own for a number, its length for a string, its size for a list.
max number The ceiling, read the same way as min.
pattern text A regular expression every string the value carries has to match. Unanchored: write ^..$ to hold the whole of it.

content.taxonomies

One block per taxonomy, each named by its id.

Key Shape Does
key text The frontmatter field its terms are read from. Defaults to the taxonomy's own id.
entities text The content { entities { } } registry its terms are ids in.
credit author | editor | translator | contributor | illustrator | reviewer | publisher What a page claims about the entities it names here, for the surfaces that can spell it.
describe flag Let a term written as a profile page be described by it, instead of generating a listing beside it.
sort order | date | title What a term's members are ordered by. Defaults to title, since a term spans collections.
reverse flag Reverse that order, for the newest-first a dated term listing wants.
content.taxonomies.listing

Generate a page per term, and an index of the terms. Its presence turns them on; #false turns them off again.

Key Shape Does
size number Members per term page. Omitted, a term's listing is one page.
template text The layout those listings render through.
prefix text The path segment before a term page's number, as in /tags/rust/page/2/.

content.entities

One block per registry, each named by its id: what its entities carry and where they come from.

Key Shape Does
shape person | organization A named field set to take instead of declaring one.
unknown error | warn | synthesize What a reference to an entity nobody declared means. Defaults to error where there is a roster, synthesize where there is not.
content.entities.fields

What every entity carries, one line per field. Declaring a field requires it; with a shape, a field of the same name replaces that shape's and any other is added.

Key Shape Does
type any | str | bool | int | float | date | dict | list | list<..> | one-of<..> The shape the value must have, also writable as the leading positional: title "str". A list names what it holds: list<int>, list<dict>.
optional flag Let the field be absent. Declaring a field otherwise requires it.
default text What the page gets when it writes none, which lets the field be absent.
min number The floor the value is held to: its own for a number, its length for a string, its size for a list.
max number The ceiling, read the same way as min.
pattern text A regular expression every string the value carries has to match. Unanchored: write ^..$ to hold the whole of it.
content.entities.slots

Which field answers each question a renderer asks of an entity.

Key Shape Does
display text The field holding the name a reader sees. Defaults to name, then title, then the entity's own id.
url text The field holding the entity's own canonical URL, off this site.
image text The field holding a picture of it: an avatar, a logo, a cover.
email text The field holding a contact address.
same-as text The field holding the other URLs that are also this entity.
content.entities.sources

Where the entities come from, read in the order written.

Key Shape Does
pages path A directory of profile pages: each page's frontmatter is one entity's fields.
data path A KDL roster file, written exactly as an inline block is.
content.entities.sources.inline

Entities written here, one block per id, each holding its fields.

content.reading

How a page's reading estimate is measured.

Key Shape Does
wpm number Words a reader gets through in a minute, for page.reading.minutes.

content.markdown

Whether .md files are pages, and what one may contain. markdown #false is markdown { enabled #false }.

Key Shape Does
enabled flag Whether a .md file under content/ is a page at all.
extensions [-](tables* | footnotes* | strikethrough* | tasklists* | smart) .. Parser extensions to enable, or -name to disable one. A * marks the ones already on.
html refuse | drop What raw HTML in a page does: refuse the build, or drop it.
eval flag Whether a fence marked eval runs as Typst. Turn it off for content you did not write: it runs at build time.

content.history

What git knows about each page, as page.git. Its presence turns it on.

Key Shape Does
contributors flag Gather everyone who has changed a page, not only the commit that last did.

languages

One block per language, each named by its code.

Key Shape Does
name text The language's name in its own language, for a switcher.
dir text Writing direction, ltr or rtl.
site text The site name in this language.
author text The default author in this language.
description text What the site is, in this language.
wpm number Words a reader of this language gets through in a minute.
strings key value .. This language's UI string table, one key value line per entry.

assets

The pipeline applied to the asset tree.

Key Shape Does
bundle flag Bundle JavaScript modules into one file per entry point.
fingerprint flag Put a content hash in each asset's filename, so it can be cached forever.
tsconfig path The tsconfig.json TypeScript and JSX are transformed against. Unset, one is discovered per script.

assets.minify

What is minified. Its presence turns every kind on; #false turns them off again.

Key Shape Does
css flag Minify stylesheets.
js flag Minify JavaScript. Needs assets { bundle }, which is what runs it.

assets.targets

The oldest browser versions the stylesheets must run on. Naming any compiles the CSS down to them.

Key Shape Does
android version Oldest Android WebView.
chrome version Oldest Chrome.
edge version Oldest Edge.
firefox version Oldest Firefox.
ie version Oldest Internet Explorer.
ios version Oldest Safari on iOS.
opera version Oldest Opera.
safari version Oldest Safari.
samsung version Oldest Samsung Internet.

assets.sourcemap

What becomes of each kind of asset's source map. Embeds the original sources, so asking for one publishes them.

Key Shape Does
scripts off | inline | external | hidden What becomes of the source map for a bundled script.
styles off | inline | external | hidden What becomes of the source map for a processed stylesheet.

assets.images

Image markup and build-time processing.

Key Shape Does
lazy flag Mark images loading="lazy".
extract flag Write images typst embedded in the page out as their own files.
assets.images.optimize

Per-format lossless recompression.

assets.images.optimize.png

Optimize PNGs. Its presence turns them on; the attributes tune it.

Key Shape Does
level number Compression effort, 0 to 6. Higher is slower and smaller.
strip none | safe | all Which ancillary chunks to discard.
assets.images.optimize.jpeg

Optimize JPEGs. Its presence turns them on; the attributes tune it.

Key Shape Does
quality number Encoder quality, 1 to 100.
assets.images.responsive

Generate width variants and a srcset. Its presence turns them on; #false turns them off again.

Key Shape Does
widths number .. The pixel widths to emit a variant at.
quality number Encoder quality for the generated variants, 1 to 100.
sizes text The sizes attribute put on every responsive image.

assets.tailwind

A utility stylesheet generated from the class names the site is written with. Its presence turns it on.

Key Shape Does
path asset path Where the sheet is served from, relative to the asset root.
scan text .. The trees and files read to find class names. Unset, the content and template trees.
config path An encre-css configuration file (TOML): theme, safelist, shortcuts, preflight.
preflight flag Whether the sheet opens with the reset rules Tailwind puts in front of its utilities.

html

Post-processing of typst's HTML output.

Key Shape Does
pretty flag Indent the emitted HTML.
embed flag Inline processed assets into the page as data: URIs.
jsonld flag Emit JSON-LD structured data for each page.
spans flag Stamp each element with the source span it came from, so serve can open it.
footnotes text .. The elements a page's footnotes belong inside, most specific first.

html.meta

The <meta> description, Open Graph and Twitter tags. On by default; #false turns them off.

Key Shape Does
twitter text The site's account for twitter:site, as @handle.
image text The preview image for a page that names none and gets no generated card.

html.anchors

Give every heading an id, and optionally a link back to it. On by default; #false turns it off.

Key Shape Does
levels number .. The heading levels that get an id, as 1 to 6. Unset, every level does.
link text The text of a link back to each heading, e.g. #. Unset or empty, no link is emitted.
place after | before Which side of the heading's text that link sits on.

html.region

Which part of a rendered page is its prose.

Key Shape Does
element text The element whose contents are the page's prose, by tag name. A page without one counts whole.
ignore text .. Elements to leave out of it, by tag name, one word each.

html.math

Where the CSS that typst's MathML output depends on lives.

Key Shape Does
styles link | inline | none Where the CSS that MathML needs lives: a served link, typst's inline block, or none.
path asset path Where the stylesheet is served from, relative to the asset root.

html.highlight

Class a code block's tokens (sx-keyword, ..) instead of colouring them inline.

Key Shape Does
prefix text What every emitted class starts with. Empty for none.
tokens [-](comment* | string* | escape* | number* | constant* | keyword* | operator* | punctuation* | function* | type* | namespace* | tag* | attribute* | property* | variable* | parameter* | heading* | strong* | emph* | link* | raw* | label* | invalid*) .. The tokens that reach the page, or -name to drop one. All are on.
classes key value .. Per-token class names, prefix aside: keyword "kw" writes sx-kw.
scopes flag Also stamp each span with the grammar's own scope, as data-scope.

The shape of generated URLs, and how strictly links are checked.

Key Shape Does
style clean | flat Whether URLs are directories (clean) or .html files (flat).
backlinks flag Hand each page the pages whose content links to it, as page.backlinks.

redirects

The old paths this site still answers for, and how it answers them.

Key Shape Does
file flag Write a _redirects rule file instead of an HTML stub per path. A wildcard or a status needs it.

redirects.rules

One line per old path, each naming where its content moved.

Key Shape Does
status number The HTTP status the host answers with, 300 to 399. Defaults to 301.

check

What the build verifies about the pages it produced. Its presence turns the markup rules on; #false turns them off again.

Key Shape Does
strict flag Fail the build on a finding instead of warning. A rule naming its own severity keeps it.
links flag | off | warn | error Report an internal link that resolves to no page. error by default, so a broken link fails the build.
orphans any | authored Report the pages nothing links to, counting any page's links or only those an author wrote.
alt flag | off | warn | error Report an image with no alt attribute at all (an empty one marks it decorative).
ids flag | off | warn | error Report an id used more than once on a page.
aria flag | off | warn | error Report an unknown ARIA role or attribute, and one referring to an id that is not there.

check.external

Check outbound http(s) links over the network. Its presence turns it on; #false turns it off again.

Key Shape Does
fresh duration How long a link that answered is trusted before it is asked again.
timeout duration How long one request may take before the link counts as unreachable.
concurrency number How many links are fetched at once. Unset, as many as the build has threads.
ignore text .. Globs, matched against each URL without its scheme, that are never requested: ignore "*.internal/**".
accept number .. Status codes that count as alive, beyond the 2xx and 3xx that always do.

check.headings

Report a heading that skips a level, e.g. h2 straight to h4. headings "warn" is headings { level "warn" }.

Key Shape Does
level flag | off | warn | error How loud a skipped level is.
start number The level a page's own sections open at, as 1 to 6. The first heading under the layout's own may land there without counting as a skip.

check.budget

How many bytes one page may ship.

Key Shape Does
strict flag Fail the build when a page is over. Off, the same report is a warning.
html size The page's own markup, as written to the output directory.
js size Every script the page loads, plus its inline <script> bodies.
css size Every stylesheet it loads, plus its inline <style> bodies.
images size Every image it references, responsive alternatives excluded.
total size All of the above at once: the page's whole transfer weight.

check.snippets

One line per code fence language, saying how a snippet of it is checked.

Key Shape Does
run text The command that checks one snippet, {file} standing for the file it is written to and {lang} for its language. Without one, this build's parser for the language checks it.
hidden text A line prefix that checks a line without showing it, for the context a fragment needs to stand on its own. Only at the very start of a line.

security

What the built pages tell a browser to trust.

Key Shape Does
sri flag Stamp integrity onto every emitted script and stylesheet. Needs assets { fingerprint }.

security.csp

The content security policy written into _headers. Its presence turns it on; #false turns it off again.

Key Shape Does
enforce flag Enforce the policy. Off reports violations without blocking anything.
hashes flag Add the digest of every inline script and style the build produced. Turns html { pretty } off, since a digest has to cover the bytes as served.
default text default-src: what every unstated fetch directive falls back to.
script text script-src.
style text style-src.
img text img-src.
font text font-src.
connect text connect-src.
frame text frame-src.
object text object-src.
base text base-uri: what a <base> may repoint relative URLs at.
form text form-action: where a form may submit.
report url report-uri: where a violation report is posted.

headers

What a host is told about the built files. Its presence writes _headers; #false keeps the policy and drops the file.

headers.cache

The Cache-Control the built files are served with, by this file and by every destination that can say so. Its presence turns it on; #false turns it off again.

Key Shape Does
immutable text The Cache-Control value for fingerprinted assets, which can be cached forever.
default text The Cache-Control value for everything else.

headers.rules

Headers of the site's own, one block per path pattern, applied before the derived ones.

generate

The files a build emits beside the pages.

Key Shape Does
sitemap flag Write sitemap.xml.

generate.robots

Write robots.txt. Its presence turns it on; #false turns it off again.

Key Shape Does
disallow text .. Paths to disallow, one word each.

generate.llms

Write llms.txt. Its presence turns it on; #false turns it off again.

Key Shape Does
summary text A one-line description of the site, put at the top of the file.

generate.manifest

Write manifest.webmanifest. Its presence turns it on; #false turns it off again.

Key Shape Does
name text The installed app's name. Defaults to the site title.
short text The name a launcher shows when the full one does not fit.
description text One line about the app, shown by an install prompt.
display standalone | fullscreen | minimal | browser How the installed app is presented.
theme text CSS colour of the browser UI around the app, and of every page's theme-color.
background text CSS colour painted before the first page has rendered.
start text Where launching the installed app lands, per language. Defaults to the language's root.
scope text The URLs the installed app covers, per language. Defaults to the language's root.
generate.manifest.icons

One line per icon, each named by the path it is served from.

Key Shape Does
size number The square edge in pixels. Absent means the image scales to any size.
purpose any | maskable | monochrome What a launcher may do with the image.

generate.feed

Write syndication feeds.

Key Shape Does
formats (rss | atom | json) .. Which feed formats to write, one word each.
limit number How many of the newest pages a feed carries.
content summary | full How much of each page an entry carries: its summary, or its prose as well.
terms flag Also write a feed per taxonomy term.
generate.feed.names

What each format's file is called, if not the conventional name.

Key Shape Does
rss path The RSS file's name, e.g. index.xml. Defaults to rss.xml.
atom path The Atom file's name. Defaults to atom.xml.
json path The JSON Feed file's name. Defaults to feed.json.

Write a client-side search index.

Key Shape Does
index terms | documents Where postings come from: terms prebuilds them, documents ships the prose for the client to index.
stopwords text .. Words to leave out of the index, one word each.
minimum number The shortest word the index keeps.
snippet number Characters of context a hit shows. 0 shows none, and ships none.
generate.search.fields

What each part of a page is worth to a hit's score. A field at 0 is left out of the index.

Key Shape Does
title number What a match in the page's title is worth.
tags number What a match in the page's taxonomy terms is worth.
body number What a match in the page's prose is worth.
generate.search.ui

Ship the generated command palette. Its presence turns it on; #false turns it off again.

Key Shape Does
hotkey text The key that opens the palette when nothing else has focus. Cmd/Ctrl-K is always bound.
placeholder text The search box's placeholder text.
limit number How many hits the palette shows.
styles flag Inject the palette's own stylesheet. #false leaves it entirely to the site's CSS.

artifacts

What a page is drawn as beyond its HTML, each from a paged second compile.

artifacts.cards

Draw a social card per page. Its presence turns it on; #false turns it off again.

Key Shape Does
template text The typst template each card is drawn with.
width number Card width in pixels.
height number Card height in pixels.

artifacts.pdf

Typeset PDFs beside the pages.

artifacts.pdf.pages

A PDF per page, beside its HTML. Its presence turns it on; #false turns it off again.

Key Shape Does
template text The typst template each page is typeset with.

artifacts.bundles

One block per bound document, each named by the id its files are written under.

Key Shape Does
collections text .. Which collections the bundle binds, one word each.
site flag Bind every page in the site rather than named collections.
title text The document's title. Unset, the bound collection's title, or the site's.
sort order | date | title How the bound pages are ordered. Unset, each collection's own sort.
reverse flag Reverse the order the pages are bound in.
formats (pdf | epub) .. What the bundle is written as. Unset, pdf.
template text The paged typst template the PDF is laid out with.

How a visitor moves between the built pages.

Client-side navigation between pages. Its presence turns it on; #false turns it off again.

Key Shape Does
root text The element swapped out on navigation.
prefetch none | hover | visible When to fetch a page ahead of the click.

Export the whole site as one HTML file. Its presence turns it on; #false turns it off again.

Key Shape Does
file path The single file the site is written to.
entry text The page that file opens on.
router hash | history How it addresses pages once opened.

Browser prefetch and prerender hints. Its presence turns them on; #false turns them off again.

Key Shape Does
prefetch none | conservative | moderate | eager | immediate How eagerly the browser fetches a linked page.
prerender none | conservative | moderate | eager | immediate How eagerly it renders one ahead of the click.

prune

Delete anything under the output directory that this build did not produce. On by default; #false turns it off, and keep narrows it.

Key Shape Does
keep text .. Globs, relative to the output directory, that the sweep never deletes: keep "themes/**".

cache

Where incremental build state lives, and whether to use it.

Key Shape Does
dir path Where incremental build state is kept.
incremental flag Reuse that state. Off, every build is a cold one.

typst

Typst engine knobs: language features, inputs, fonts, package registry.

Key Shape Does
features [-]text .. Typst language features to enable, or -name to disable one. html cannot be removed.
inputs key value .. Values passed to every compile as sys.inputs, one key value line per entry.
registry url Where typst packages are fetched from.

typst.fonts

Where a compile looks for glyphs.

Key Shape Does
paths text .. Directories scanned recursively for fonts, searched before the system's own.
system flag Also use the fonts installed on the machine. Off, a build sees only what the project ships.

hooks

External commands run before and after the build.

Key Shape Does
before text .. Commands run before the asset pipeline, so what they generate is picked up.
after text .. Commands run once the output directory is written.

announce

Where to announce the site's metadata.

announce.standard

Announce to standard.site over atproto. Its presence turns it on.

Key Shape Does
handle text The atproto handle the site is announced under.
did text That handle's DID, if it should not be resolved at build time.
pds url The personal data server the record is written to.
discover flag Show the publication on standard.site's discovery surfaces.
icon path An icon published with the record.
announce.standard.verify

Which handle-verification artifacts the build emits.

Key Shape Does
wellknown flag Write /.well-known/site.standard.publication, naming the publication record.
links flag Add the verification links to the page head.

deploy

Where baudelaire deploy uploads the built site.

deploy.s3

Upload to S3 or an S3-compatible bucket. Its presence turns it on.

Key Shape Does
bucket text The bucket uploaded into.
endpoint url The API endpoint, for an S3-compatible host such as R2.
region text The bucket's region.
prefix text A key prefix every uploaded object goes under.
delete flag Delete remote objects this build did not produce.
concurrency number How many objects are transferred at once. Unset, as many as the build has threads.

deploy.ssh

Upload over SSH. Its presence turns it on.

Key Shape Does
host text The host uploaded to.
path text The remote directory the site is written into.
port number The SSH port.
user text The user to connect as.
key path The private key to authenticate with. Prefer an ed25519 key.
strict flag Verify the host key against known_hosts, learning an unseen host on first connect and refusing a changed one.
delete flag Delete remote files this build did not produce.

serve

The development server.

Key Shape Does
port number The port the dev server listens on.
bind text The address it binds. Defaults to loopback; it has no authentication.
open flag Open a browser when the server starts.
watch flag Watch the sources and rebuild. Off, it serves what is already built.
include text .. Extra paths to watch, one word each.
exclude text .. Paths to leave unwatched, one word each.
editor text .. The command alt-clicking a preview element runs, program and arguments as separate words.

profiles

Named overlays, each selected with --profile and each accepting any key on this page.