Blocks reference#

Blocks are YMPrint’s special content types for things plain YAML prose can’t express — images, admonitions, code, figures, and more. Some mirror markdown (images, code blocks); others extend it (admonitions, styled horizontal rules, executable Python).

Block syntax#

A block is a key that begins with an underscore, e.g. _img or _spacer. Its value is a block-specific data structure, typically either a scalar or a mapping that allows several arguments to be passed.

Blocks appear wherever content is allowed, typically as list items:

Report:
  - Photos:
    _img:
      src: photo.png
      caption: "Figure 1"
  - _info: A short informational note.
  - _pagebreak:

All block codes accept an optional, user-defined suffix after the underscore code, e.g. _hrule_red and _hrule_blue are both handled by the _hrule block — the suffix simply keeps the YAML keys unique when you use several in one list and allows you to meaningfully identify them if you are using several in a row.

The suffix does not affect how the block is executed. It is simply an optional identifier.

Block catalogue#

Block	Purpose
`_img`	Embed an image with an optional caption.
`_matplotfig`	Embed a matplotlib figure object with an optional caption.
`_info` / `_warning` / `_danger` / `_tip` / `_note`	Callout boxes.
`_blockquote`	A quotation with attribution.
`_code`	A non-executable code block.
`_py`	Execute Python and optionally show the syntax-highlighted source.
`_loadjson`	Load variables into the document from a JSON file.
`_ul`	An unordered (bulleted) list.
`_ol`	An ordered (numbered) list.
`_pagebreak`	Force a page break, optionally switching page template.
`_nextpagetemplate`	Arm the page template to switch to at the next break.
`_textstyle`	Switch the active named text style for the rest of the section.
`_hrule`	A customizable horizontal rule.
`_spacer`	Insert vertical whitespace.

`_img` — Images#

Embed a raster image (PNG, JPEG, …) with a caption. Paths are relative to the report file (or absolute).

_img:
  src: catpuccin.png
  caption: "Figure 1: The catpuccin cat"
  scale_ratio: 0.3

Parameter	Required	Default	Meaning
`src`	✅	—	Path to the image, relative to the `.yml` file or absolute.
`caption`	✅	—	Caption text shown below the image.
`scale_ratio`		`1`	Scale factor relative to the available content width. The image is automatically shrunk to fit the frame if it would overflow.

`_matplotfig` — Matplotlib figures#

Embed a matplotlib Figure object that you built in a _py block. Pass the figure through the $var syntax.

Report:
  - _py:
      echo: false
      source: |
        import matplotlib.pyplot as plt
        fig, ax = plt.subplots()
        ax.plot([0, 1, 2], [0, 1, 4])
  - _matplotfig:
      fig: $fig
      caption: "Figure 1: A computed plot"
      scale_ratio: 0.8

Parameter	Required	Default	Meaning
`fig`	✅	—	A matplotlib `Figure`, passed as `$var`.
`caption`		`""`	Caption text shown below the figure.
`scale_ratio`		`0.8`	Scale factor relative to the available content width. The figure image is automatically shrunk to fit the frame if it would overflow.

Note

matplotlib is an optional dependency — install it in the same environment as YMPrint to use this block.

Admonitions#

Callout boxes for drawing attention. Five variants are available, each taking the callout text as its value:

Report:
  - _info: Here is an "info" admonition.
  - _warning: Here is a "warning" admonition.
  - _danger: Here is a danger admonition.
  - _tip: Here is a helpful tip.
  - _note: This is useful when you want to give a note.

Block	Use for
`_info`	General information.
`_warning`	Something the reader should be careful about.
`_danger`	A serious caution.
`_tip`	A helpful suggestion.
`_note`	An aside worth remembering.

`_blockquote` — Block quotes#

A quotation with an attribution line.

_blockquote:
  quote: “What you do makes a difference, and you have to decide what kind of difference you want to make.”
  attribution: Jane Goodall

Parameter	Required	Meaning
`quote`	✅	The quotation text.
`attribution`		Who said it.

`_code` — Preformatted code#

A non-executable, code block for pre-formatted text. Use this to display code or config verbatim.

_code:
  source: |
    yaml_data: is being shown
    you can put: any yaml data together
    more examples:
      - - cell-padding
        - cell_size

Parameter	Required	Meaning
`source`	✅	The literal text to display. Use a YAML block scalar (`
`line_numbers`		—
`caption`		—
`width_ratio`		`0.75`

To run code instead of just showing it, use _py.

`_py` — Executable Python#

Execute Python with exec(). The document’s variable dictionary is the global scope, so any _vars you defined are available to the code, and any variables the code creates become available to the rest of the document (and to blocks via $var).

_py:
  echo: true
  line_numbers: true
  namespace: py1
  caption: >
    Once this executes, the variables are accessible under the py1 namespace.
  source: |
    import math
    a = 3
    b = 4
    c = math.sin(a / b)

Note

The | after source: tells the YAML parser that this is preformatted text, to respect the line breaks exactly as written, and that text should not be wrapped.

This is in contrast to the > character, often used when writing paragraph content, which allows you to break lines wherever you want in the YAML without breaking lines in the finished document.

Both the | and > character are part of the YAML spec.

Parameter	Required	Default	Meaning
`source`	✅	—	Python source to execute.
`echo`		`true`	Whether to render the source as a highlighted code block. Set `false` to run silently.
`line_numbers`		—	Show line numbers alongside the rendered source.
`caption`		—	Caption shown with the rendered code.
`namespace`		—	Nest the created variables under this name (access as `{{namespace.var}}`). Without it, variables land at the top level.
`width_ratio`		`0.75`	Width of the rendered code block relative to the content width.

Warning

_py runs exec() in the same Python environment as YMPrint. External subprocess isolation is not currently implemented. Only run documents you trust.

YMPrint is not intended to be operated as a public-facing web app.

After execution the variables are usable everywhere:

  - - a = {{py1.a}}
    - b = {{py1.b}}
    - c = {{py1.c}}

See Variables → Computing variables in Python.

`_loadjson` — Load JSON variables#

Read a JSON file into your variable context at render time, optionally under a namespace.

_loadjson:
  path: extra_vars.json
  namespace: extra_vars

Parameter	Required	Meaning
`path`	✅	Path to the JSON file, relative to the report file.
`namespace`		Nest the loaded values under this name (access as `{{namespace.key}}`). Without it, they load at the top level.

  - - bn = {{extra_vars.bn}}
    - dx = {{extra_vars.dx}}

`_ul` — Unordered lists#

A bulleted list. A bare YAML list is a sequence of paragraphs/sub-sections, so bullets are written explicitly with _ul. Nest a list inside an item to indent (the bullet glyph changes with depth, default hierarchy •‣⁃∘).

Findings:
  _ul:
    - The handrail is loose on the north stair.
    - Two ceiling tiles are water-stained in the lobby.
    - - a nested sub-point
      - another sub-point

_ul works as the value of a heading key (as above) or as a list item (- _ul: [...]). Bullet glyph, colour, and indentation come from _style.body.bullets (see Configuration → Text styles).

`_ol` — Ordered lists#

A numbered list. Numbering is automatic by position; nesting a list inside an item creates a nested numbered list.

Recommended actions:
  _ol:
    - Re-secure the handrail.
    - Replace the stained ceiling tiles.
    - - Nested step one
      - Nested step two

`_pagebreak` — Page breaks#

Force a page break. Called with no value, it just breaks the page and keeps the current page template. Pass the name or 0-based index of a page template to switch to it for the pages that follow.

Report:
  - >
    This content ends the page.
  - _pagebreak:            # break, keep the current template
  - >
    This content starts a new page.
  - _pagebreak: body       # break AND switch to the "body" template
  - _pagebreak: 1          # equivalently, by index

`_nextpagetemplate` — Switch template at the next break#

Arm the page template to switch to at the next page break, without inserting a break itself. Useful when the break is produced elsewhere (for example, by content overflowing the page). Takes the template name or 0-based index.

Report:
  - _nextpagetemplate: body   # the next page break will switch to "body"
  - >
    Long content that flows onto a second page, which will use the "body" template.

`_textstyle` — Switch text style#

Activate a named text style for the rest of the section it appears in, and for every nested descendant. Takes a style name (declared under _style.styles) or the special name default. It renders nothing of its own.

The switch is scoped to its list: it restyles every following sibling plus their descendants, then reverts automatically when the section ends — no manual switch-back is needed unless you want to change style again within the same section. Switching swaps the whole family, so body paragraphs, bullet lists, and derived headings all follow the active style. An undeclared style name raises an error.

Legal disclaimer:
  - _textstyle: fine-print     # applies from here down in THIS section
  - This paragraph is fine-print.
  - Sub-clause:
      - Inherited fine-print (a nested descendant).
  - _textstyle: default        # switch back within the same section
  - Back to the default style.

Next section:
  - Body style again — the disclaimer's scope ended with its list.

See Switching text styles for the full behaviour.

`_hrule` — Horizontal rules#

Unlike a markdown rule, _hrule is configurable — width, thickness, colour, and line cap. Use suffixes to keep multiple rules unique in one list.

- _hrule_default: null
- _hrule_red:
    width_ratio: 0.8
    thickness: 2
    color: "#bb3322"
- _hrule_blue:
    width_ratio: 0.6
    thickness: 3
    color: "#4422dd"
    cap: round

Parameter	Default	Meaning
`width_ratio`	`1.0`	Rule width as a fraction of the content width.
`thickness`	`1`	Line thickness in points.
`color`	`#111111`	Rule colour.
`cap`	`square`	Line-cap style: `square` or `round`.

Passing null (as with _hrule_default: null) draws a rule with all defaults.

`_spacer` — Vertical space#

Insert an arbitrary amount of vertical whitespace, measured in points, to nudge content positioning by hand.

Report:
  - _spacer: 5
  - There is a 5 pt spacer above.
  - _spacer: 20
  - There is a 20 pt spacer above.

The value is the height of the space in points.

Tip

A _spacer: 0 is a handy trick to stop a paragraph being misinterpreted as a bullet when it’s immediately followed by a list.

Blocks reference#

Block syntax#

Block catalogue#

_img — Images#

_matplotfig — Matplotlib figures#

Admonitions#

_blockquote — Block quotes#

_code — Preformatted code#

_py — Executable Python#

_loadjson — Load JSON variables#

_ul — Unordered lists#

_ol — Ordered lists#

_pagebreak — Page breaks#

_nextpagetemplate — Switch template at the next break#

_textstyle — Switch text style#

_hrule — Horizontal rules#

_spacer — Vertical space#

`_img` — Images#

`_matplotfig` — Matplotlib figures#

`_blockquote` — Block quotes#

`_code` — Preformatted code#

`_py` — Executable Python#

`_loadjson` — Load JSON variables#

`_ul` — Unordered lists#

`_ol` — Ordered lists#

`_pagebreak` — Page breaks#

`_nextpagetemplate` — Switch template at the next break#

`_textstyle` — Switch text style#

`_hrule` — Horizontal rules#

`_spacer` — Vertical space#