Images, figures and video¶

These directives place a picture or a video player on the page. ubCode renders all three in the editor preview and in its html and pdf builds.

Images¶

The image directive shows a picture, from a file in the project or an https:// URL.

reStructuredText

An image

.. image:: /_static/ubCode_icon_light.svg
   :alt: The ubCode mark
   :width: 64px

MyST

```{image} /_static/ubCode_icon_light.svg
:alt: The ubCode mark
:width: 64px
```

The MyST form renders live in the MyST image.

A local path is looked up relative to the document that names it, or to the source directory when it starts with /; a remote https:// URL is loaded directly. These options affect how the image is displayed:

:alt:: Alternative text, shown if the image cannot be loaded and read by screen readers.
:width: / :height:: The displayed size: a number with a unit (64px, 2em), or for :width: a percentage.
:scale:: Scales the image by a percentage.
:align:: Aligns the image: left, center, or right (not yet in ubc build html; see the image differences).
:name:: An identifier for the image, registered as a cross-reference target, so :ref:`my-image` links to it.
:target: / :class:: A link the image opens, and extra CSS classes.

A * wildcard extension (.. image:: logo.*), and the other places an image path is resolved differently from a Sphinx build, are in the image differences.

Figures¶

The figure directive is an image with a caption: the first paragraph of its body becomes the caption, and any paragraphs after it form a legend under the image.

reStructuredText

A figure

.. figure:: /_static/ubCode_icon_light.svg
   :alt: The ubCode mark
   :width: 96px

   The ubCode mark.

   A legend: any paragraph after the caption.

MyST

```{figure} /_static/ubCode_icon_light.svg
:alt: The ubCode mark
:width: 96px

The ubCode mark.

A legend: any paragraph after the caption.
```

The MyST form renders live in the MyST figure.

A figure takes the image options above, except that :align: aligns the whole figure (not yet in ubc build html), and adds two of its own:

:figwidth:: The width of the figure, as opposed to the image inside it.
:figclass:: Extra CSS classes for the figure.

A figure’s :name: names the whole figure, as in a Sphinx build, and in built output its caption gains a ¶ permalink. If a heading on the same page already has that name’s anchor — a heading of the same words, say — the heading keeps it and the figure gets a numbered one (my-figure-1 in ubCode, id1 in a Sphinx build); a :ref: to the name still lands on the figure. Give the figure a name of its own for an anchor that does not change.

Videos¶

The video directive embeds a video with the browser’s own player. Its argument is one source file or URL, optionally followed by a second source as a format fallback — the player uses the first source it can play.

reStructuredText

A video

.. video:: /basics/quickstart.mp4
   :poster: /basics/quickstart.poster.png
   :width: 480
   :muted:

MyST

```{video} /basics/quickstart.mp4
:poster: /basics/quickstart.poster.png
:width: 480
:muted:
```

The MyST form renders live in the MyST video.

The directive comes from the third-party sphinxcontrib-video package, which a Sphinx build needs installed. ubCode implements it natively — it only needs the extension name listed in your parsing configuration:

[parse]
extensions = ["sphinxcontrib.video"]

A local source, and the :poster: image, is resolved like an image path and copied into the build output with your other assets; a remote https:// URL is passed through and never downloaded. In the editor’s Rendered preview a local video shows the player but does not play; the same source plays in the output of ubc build html. These options are applied:

:autoplay: / :loop: / :muted: / :playsinline:: Flags passed to the player as the matching HTML5 attributes.
:nocontrols:: Hides the player controls, which are otherwise shown.
:controlslist:: A comma-separated subset of nodownload, nofullscreen, and noremoteplayback, hiding individual browser controls.
:alt:: Fallback text shown when the video cannot be played.
:poster:: An image shown before the video plays.
:preload:: A loading hint for the browser: auto, metadata, or none.
:width: / :height:: The player’s size in pixels (bare numbers). :width: also accepts a percentage such as 50%, in which case the width scales with the page and any :height: is ignored.
:caption: / :figwidth:: A caption renders the video as a captioned figure; :figwidth: sets that figure’s width (a number with any CSS unit or %) and only applies when a caption is present.
:class: / :align:: Extra CSS classes for the player, and its alignment (left, center, or right).

An invalid option value never fails a build: the video renders without it, and an out-of-set :align: or :preload:, or an unreadable :figwidth:, is reported (a Sphinx build checks :figwidth: not at all and writes it into the page as given). Anything after the second source is ignored, where a Sphinx build reports an error, and a body is accepted but never rendered.

Note

A page cannot play a video, so ubc build pdf prints the :poster: image in its place, and a video with no readable poster is reported (build.pdf_block_unsupported).