11. Visibility and themes

Scope blocks per site, template, or backend with @only / @except, and restyle a whole site in one line.

Before you start: Render targets

Any block can carry @only(...) or @except(...) to scope it by three axes: sites (site names), templates (:webpage / :book / :presentation), and backends (:html / :pdf / :markdown). @only renders the block only where the conditions match; @except everywhere else. This is how one document serves a web build and a print PDF without forking content.

Themes recolour the whole site in one line: theme = :nord (or tokyonight, gruvbox, catppuccin, rose, paper), each with dark and light variants — add theme_toggle = true for the switcher button. Local styling stays available through class blocks, which always win over theme defaults.

§ 1Exercise: A print-aware, themed page

Theme your site, then add one block that skips the PDF and one that renders only in it.

site docs {
  default_template = :book
  title            = "Project Docs"
  theme            = :gruvbox
  theme_toggle     = true
  toc { chapter "Intro" { page = index } }
}

page index { sites = [:docs]  start = true
  h1 "Project docs"
  @except(backends=[:pdf]) video { src = "demo.mp4" }
  @only(backends=[:pdf])   p "See the online docs for the screencast."
}