5. Images and assets

Embed images on pages and in diagrams, and understand how assets ship with the build.

Before you start: Formatting, callouts, and columns

An image block takes its source path as the inline label, resolved relative to the build entry file; the file is copied into _wdoc/ at build time so the output site is self-contained. Set width / height to size it and alt for accessibility. Because the copy is referenced by a relative URL, it resolves when the site is served — not when a page is opened directly from disk.

Icons need no asset at all: :pack.name: (for example :lucide.rocket:) drops a glyph inline anywhere prose renders. An image is also a placeable diagram shape, positioned by x / y next to rects and circles.

§ 1Exercise: Ship a screenshot

Add an image to a page with alt text and a fixed width, build, and find the copied file in the output.

page media { sites = [:docs]
  h1 "Media"
  p "The dashboard :lucide.gauge: looks like this:"
  image "assets/dashboard.png" {
    alt   = "The dashboard on first boot"
    width = 480.0
  }
}