Skip to content

Add images and diagrams

Reference image files from topics with <image>. They are published with the release and shown only to readers who can see a topic that uses them.

  1. Put the file in the project, for example in images/.

    SVG, PNG, JPEG, GIF and WebP are served on the site and embedded in PDFs. For diagrams, prefer SVG with a <title> and <desc> and a solid background, so it reads in both light and dark themes. The diagrams on the overview are hand-written SVG.

  2. Reference it with a path relative to the topic, and always give alternative text.
    <fig id="fig-architecture">
      <title>The hosted platform</title>
      <image href="../images/architecture.svg" placement="break">
        <alt>Diagram: the docs repository sends a push webhook to the web service...</alt>
      </image>
    </fig>

    placement="break" puts the image on its own line; without it the image is inline. width and height are passed through. keyref works too, with the key's href naming the file.

  3. Validate.

    A missing file is an error, missing-image. External images (an https: URL or scope="external") are not checked and are not embedded in PDFs.

On the hosted site, images are served from /_assets/ only when a topic visible to the signed-in reader references them, so guessing a path reveals nothing. Author files, SVG included, are served with a sandboxing Content Security Policy.