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.
-
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. -
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.widthandheightare passed through.keyrefworks too, with the key'shrefnaming the file. -
Validate.
A missing file is an error,
missing-image. External images (anhttps:URL orscope="external") are not checked and are not embedded in PDFs.
Results
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.