Figures, images, and diagrams¶
Figures¶
To number and caption an image, put it inside a figure block:
:::{figure} path/to/image.ext
:alt: A descriptive text.
:name: unique-id
Figure caption.
:::
This produces the following output.
Fig. 1 A duck teaching something.¶
Figures can be referenced using the standard cross-referencing markup.
Images¶
To insert an image, write .
(Note the leading exclamation mark.)
The image is inserted at that exact point.
For example,  in a paragraph
produces while in its own paragraph produces
The text between the square brackets [...] is used as the alt tag for an accessible description of the image.
Icons¶
The theme also has support for FontAwesome v7 icons. To
use an icon from this set, use the {fa-icon}`code-point` role, passing the desired icon code-point.
For example {fa-icon}`f303` produces the pencil useful for the time block.
Diagrams¶
The OU Book Theme comes with the Mermaid diagram-generation system ready to use.
Use standard Mermaid notation inside a mermaid block to produce flowcharts, mindmaps, radar charts,
UML and other diagrams.
You can find the full set of available Mermaid functionality in the Mermaid documentation. The following example shows the Markdown necessary for embedding Mermaid code, in this case a flowchart, in Markdown:
:::{mermaid}
:caption: Publishing workflows from MyST markdown
:name: mermaid-workflow
flowchart LR
A[Jupyter Notebook] --> C
B[MyST Markdown] --> C
C([mystmd]) --> D{Sphinx
+
pandoc}
D --> LaTeX --> PDF
D --> Word
D --> XML --> OX[OU-XML] --> OU-VLE
D --> HTML
OX --> OU-PDF
:::
This produces the following output:
flowchart LR
A[Jupyter Notebook] --> C
B[MyST Markdown] --> C
C([mystmd]) --> D{Sphinx
+
pandoc}
D --> LaTeX --> PDF
D --> Word
D --> XML --> OX[OU-XML] --> OU-VLE
D --> HTML
OX --> OU-PDF
Fig. 2 Publishing workflows from MyST markdown¶
If you provide a caption and name attribute, Mermaid diagrams are treated as figures and can be
referenced using the standard cross-referencing markup.
Horizontal lines¶
Write three hyphens (---) on a line of their own to display a horizontal line.
Keep a blank line before and after the hyphens. This produces a line like this:
Tip
The M269 book uses horizontal lines in the middle of explaining a concept or algorithm for the student to ‘pause and think’ about a question, before they read the solution / discussion after the line. Using an exercise or activity for this would be too strong a break of the narrative flow. Using an interactive element (e.g. hiding the answer paragraph) would not render in a PDF.
