Skip to content

Images

Use an img block to display an uploaded image in a document or e-mail. Set its size, alignment, caption, and alternative text.

AI-assisted, human-approvednovem uses AI to review and keep our documentation up to date.

Available in: documents and e-mails.

{{ img
  ref: logo.png
  alt: The novem logo
  width: 200px
  al: center
  caption: "Fig 1 — the logo"
  link: https://novem.io
}}

Overview

Where the vis block embeds a live novem visualisation, the img block embeds a static asset: a file you've uploaded to a plot, document or mail under its assets/ path (for example, /v1/vis/docs/:doc/assets/).

It is a leaf block, self-closing with no body. image is an alias for img.

E-mails include the image bytes in the message and reference them inline, so displaying the image does not require a remote download. Terminal (ANSI) renders show its alternative text as [image: …].

Referencing an asset

keyword: ref
options: own asset name | FQNP

The only required option. Two shapes are accepted:

{{ img ref: logo.png }}                               # asset on this document/mail
{{ img ref: ./assets/logo.png }}                      # the same, named as a file next to the source
{{ img ref: /u/alice/p/myplot/a/diagram.svg }}        # another VDE's asset (FQNP)
{{ image ref: /u/alice/p/myplot/assets/diagram.svg }} # FQNP long form

An own asset is one uploaded to the hosting document or mail itself. Name it bare (logo.png) or the way you would a file next to the source: ./logo.png, assets/logo.png, ./assets/logo.png (asset/ is accepted for the singular). The FQNP forms pull an asset from any visualisation you can read; they load through the owner's route, so the viewer needs access to that visualisation.

Options

Alt

keyword: alt
options: "accessibility text"
default: the asset's file name

Alternative text for screen readers and clients that don't render images. Also the text shown in terminal renders.

Width / Height

keyword: width / height
options: width — full, 1/2, 0.5, 80%, 200px
options: height — intrinsic, fill, 200px

Use an explicit px suffix for pixel widths. Fractions, decimals, and percentages size the image relative to its container. Heights accept intrinsic, fill, or pixels; percentage heights are invalid.

Fill, fit and bleed

keyword: height / fit / bleed
options: height — fill
options: fit — contain (default), cover
options: bleed — top, right, bottom, left, x, y, all

height: fill gives the image the leftover height of its page, or the whole of its grid area on a layout page. fit: cover crops the picture to that box; contain shows all of it. bleed runs the image out to the named page edges, past the margins and the header and footer bands, for a photograph that meets the trim.

Align

keyword: align
options: left | right | center

Positions the image within its layout when it's narrower than full width.

Caption

keyword: caption
options: "caption text"

An optional caption rendered below the image. Plain text only — markdown is not processed here.

keyword: link
options: URL

Wraps the image in a link. Accepts http(s), mailto and relative or anchor targets; other schemes are rejected.

Examples

{{ img
  ref: logo.png
  alt: Acme Research
  width: 180px
  align: center
}}

A captioned figure from another visualisation

{{ img
  ref: /u/novem_demo/p/state_pop/a/methodology.png
  alt: Methodology flowchart
  width: 80%
  caption: Figure 2 — how the population estimates are derived
}}

Inline syntax with a click-through

{ { img ref: banner.png, alt: Read the full report, link: https://novem.io/u/acme/d/q3_report } }
Next
Page references