Sites & Templates

A site block configures one output site — its template, title, theme, and navigation. A document can declare several sites; each page joins one or more via its sites field.

§ 1Fields

Child blocks

§ 2webpage template

Hugo-style site header, sticky top navbar built from menu, and a reading column.

site marketing {
  default_template = :webpage
  title            = "My project"
  root             = true
  theme            = :nord
  menu {
    item "Home"     { page = index }
    item "Docs"     { href = "docs/" }
    item "More" {
      item "About"   { page = about }
      item "Contact" { page = contact }
    }
    item "Source"   { href = "https://github.com/example/proj" }
  }
}

Menu items use page = <name> for in-site links (validated against pages in this site) or href = "…" for external or cross-site URLs. Nested items become dropdown groups.

§ 3book template

mdBook-style fixed left sidebar with nested chapters and current-chapter highlight; reading column on the right.

site docs {
  default_template = :book
  title            = "Project Docs"
  theme            = :nord
  theme_toggle     = true
  toc {
    chapter "Intro"        { page = index }
    chapter "Guide" {
      chapter "Setup"      { page = setup }
      chapter "First run"  { page = first_run }
    }
  }
}

Chapters nest to any depth. A chapter with no page = is a grouping heading. A chapter pointing at an unknown page is a build error.

§ 3.1Sidebar footer buttons

A sidebar_footer block pins one or more launcher buttons to the very bottom of the book sidebar — handy for a reference index or an external link you want reachable from every page without crowding the chapter tree. Each button takes an inline label, a page (internal, validated → <page>.html) or href (raw/external URL; page wins), and an optional icon (an icon name like lucide.chart-network). The built-in book template renders the button icon-only, using the label as its hover tooltip / accessible name (and as visible text when no icon is given). A button linking to an unknown page is a build error.

site docs {
  default_template = :book
  title            = "Project Docs"
  toc { chapter "Intro" { page = index } }
  sidebar_footer {
    button "Reference" { page = reference_page  icon = "lucide.chart-network" }
    button "Source"    { href = "https://example.com/repo" }
  }
}

Templates see the resolved buttons as TemplateCtx.footer (each with its icon already rendered to SVG markup); the built-in book template draws them via the wdoc_part_sidebar_footer(c) part.

§ 4Search

Set search = true on a site to add client-side full-text search. The build writes a per-page text index to _wdoc/search-index.json (page title from its first h1, plus the page body text) and the book and webpage templates render a search box — in the sidebar and the nav respectively — backed by a small bundled script. Typing ranks pages by title and body matches and shows the top hits with a context snippet; Enter opens the first hit, Escape clears.

§ 5presentation template

A reveal.js-style slide deck: the whole site renders into a single index.html, navigated with the keyboard. The deck block lays out the 2-D grid — each section is a column, its slides are rows — and each slide names a page that belongs to this site.

site talk {
  default_template = :presentation
  title            = "My talk"
  theme            = :catppuccin
  deck {
    section "Intro" {
      slide title
      slide agenda
    }
    section "Main" {
      slide topic
    }
  }
}

Each slide must sit on its own line (like li / chapter). A slide pointing at an unknown page is a build error. Two in-slide blocks are deck-specific:

page topic {
  h2 "Key points"
  fragment { p "Revealed on the first Space" }
  fragment { p "…then this one" }
  notes { p "Reminder: mention the benchmark numbers." }
}

§ 6Custom templates

The three built-ins are not special: a template is just a function from a TemplateCtx to a list of HTML fundamentals, and the document schema accepts your own. Declare a template <name> { render = fn(c: TemplateCtx) -> list<HtmlFundamental> … } in your document and select it with a site's default_template (e.g. :blog) or a page's template field.

The renderer hands render this context:

You rarely build a template from raw fundamentals. The stdlib exposes its own chrome as composable parts — each a function returning list<HtmlFundamental> — plus one wdoc_*_layout function per built-in that is its whole default composition. Parts resolve by bare name once you import <wdoc.wcl>.

§ 6.1Extend a built-in

To keep a whole built-in but add your own chrome, call its layout and append parts. This is the full webpage plus a footer:

template blog {
  render = fn(c: TemplateCtx) -> list<HtmlFundamental>
    flatten([
      wdoc_webpage_layout(c),
      [ HtmlFundamental::Element {
          tag: "footer", id: none, class: ["site-footer"], attrs: none,
          children: [ HtmlFundamental::Raw { html: "© 2026 — built with wdoc" } ],
      } ],
    ])
}

site myblog { default_template = :blog  title = "My blog" }

§ 6.2Rebuild from parts

To replace a region, copy the layout's body and swap one part — here a custom masthead in place of wdoc_part_header, keeping the stdlib navbar and content. Omit a part to drop that region entirely (no nav, say, for an app home page).

template app_home {
  render = fn(c: TemplateCtx) -> list<HtmlFundamental>
    flatten([
      wdoc_part_webpage_css(),      // keep the stdlib styling…
      [ HtmlFundamental::Element {  // …a hero masthead instead of wdoc_part_header
          tag: "header", id: none, class: ["hero"], attrs: none,
          children: [ HtmlFundamental::Raw { html: c.title } ],
      } ],
      wdoc_part_navbar(c),          // …reuse the stdlib nav
      wdoc_part_content(c),         // …standard content <main>
    ])
}