Callouts and media

YAML

# callout
kind: hold
title: Sample size caveat
body: |
  Only twelve weeks of post-launch data are available.

Field	Type	Required	Meaning
`kind`	one of `up`, `down`, `neutral` or `hold`	yes	The direction the callout signals.
`title`	text		The callout heading.
`body`	inline Markdown	yes	The callout text.

Callouts require kind: up|down|neutral|hold and a Markdown body; title is optional. A callout is an aside under one rule, without a fill, outline or side bar, and its body stays within the text measure. The title runs into the first paragraph in the display face, coloured by kind (up, down and hold tokens; ink for neutral); when the body opens with a list or another block, the title stands on its own line. Images require src and alt ("" marks a decorative image; the old title is alt), with optional escaped caption, fit: contain|cover|fill (default contain), positive integer width/height and a #rrggbb color. Audio and video require src and a title (the accessible name; the old alt is title), use native controls and metadata preloading, and accept an optional caption; video also accepts a safe image poster, dimensions and wide. Audio takes no dimensions or poster. Native generation embeds local media, including posters and Markdown images in body and callout content. Safe caller-provided image/audio/video data URIs are supported.

An image src may also be a credited https://images.unsplash.com/... photo (lowercase host, no userinfo or port). It is the only remote image origin a report may use, for image blocks and the title_image header alike, and it is a hotlink: no host fetches, embeds or inventories it, and the reader’s browser loads it when the report is read. Every other remote image, audio, video, poster and Markdown image (including an Unsplash one outside an image block or title_image) must still be a report file: a remote address there is a report.asset.remote error at its field, from validate and the render alike, and only that element fails. An Unsplash photo needs a credit. An optional credit mapping attributes the photo:

Field	Type	Required	Default	Meaning
`src`	text	yes		The image: a report-relative path, a data address or a credited Unsplash photo address.
`alt`	text	yes		The text alternative; `""` marks a decorative image.
`caption`	text			The caption under the image.
`fit`	one of `contain`, `cover` or `fill`		`contain`	How the image fills its box.
`width`	whole number			The image width in pixels; a positive whole number.
`height`	whole number			The image height in pixels; a positive whole number.
`credit`	mapping			The photo credit; an Unsplash photo needs one.
`credit.author`	text	yes		The photographer’s name; a non-empty string.
`credit.author_url`	text			The photographer’s profile; required on an Unsplash photo, which pins it to unsplash.com.
`credit.source`	text			The site the photo comes from; Unsplash on an Unsplash photo.
`credit.source_url`	text			The photo’s page on the source site.
`color`	any value			A #rrggbb colour that fills the box until the photo loads; another value is dropped with a warning.
`wide`	`true` or `false`		`false`	Whether the image takes the report’s full width instead of the text measure.

credit.author is required and a non-empty string; author_url, source and source_url are optional strings, except on an images.unsplash.com photo, where the credit is pinned to Unsplash: author_url is required and must be an https://unsplash.com/... address (lowercase host, no userinfo or port), source_url if present must be on https://unsplash.com/, and source if present must be Unsplash (case-insensitive). Any violation is an image.credit-invalid error at the offending credit key; the image block stays visible as source and the header image is omitted, as with image.credit-missing. Credits on local images keep the looser rule below. The image figure ends with Photo by <author> on <source> after any caption, and prints in PDF output. Each name links (target="_blank" rel="noopener noreferrer") only when its URL is plain http(s); an unsafe URL keeps the text, drops the link and warns image.credit-url. A credit without a usable author warns image.credit-invalid (header image, local images) or is a block.schema error (image block). An image served from images.unsplash.com without a credit is an image.credit-missing error: the image block stays visible as source and the header image is omitted, as with any recoverable invalid block. The same credit mapping works in a title_image mapping. richview image search|use (and the MCP tools richview_image_search and richview_image_use) find a photo and write this YAML, with the download registered as the Unsplash API guidelines require.

A hotlinked photo stays readable offline. The HTML keeps the URL and embeds no bytes. With width and height the figure reserves its box (aspect-ratio) before the photo loads, and an optional color: '#rrggbb' (the photo’s dominant colour, which richview image use writes from the API’s color) is painted behind the image, with alt text in a contrasting ink. Any other color value is dropped with an image.color-invalid warning. The caption and the credit line always render, so offline the text and credit remain and only the photo is missing. Rendering never touches the network: the Unsplash download ping happens once, at richview image use. The native PDF export loads exactly the credited images.unsplash.com photos of its image blocks and title_image (GET requests for images only; the renderer marks them data-rv-photo) and prints them as the page shows them; a photo that cannot load, or does not answer within a few seconds, prints as its box and credit with an export.photo-unavailable warning.

Field	Type	Required	Default	Meaning
`url`	text	yes		The absolute address to embed; the host must be allowed and https.
`height`	whole number		`420`	The frame height in pixels; a positive whole number.
`allow`	list of text		`[youtube.com, www.youtube.com, youtube-nocookie.com, vimeo.com, player.vimeo.com, gist.github.com, codepen.io]`	The hosts that may be embedded.
`caption`	text			The caption under the frame.
`wide`	`true` or `false`		`false`	Whether the frame takes the report’s full width instead of the text measure.

Embeds require an absolute HTTPS url. height defaults to 420; caption is optional. The default allowlist is registry::EMBED_HOSTS: youtube.com, www.youtube.com, youtube-nocookie.com, vimeo.com, player.vimeo.com, gist.github.com and codepen.io. A blocked embed is the error security.embed. An authored allow host array replaces it, matching the host or its subdomains. URLs containing credentials are blocked. Known third-party player hosts receive script/presentation/same-origin sandbox permissions; custom author-allowed hosts omit same-origin permissions. Embeds remain network-dependent.

Audio and video:

Field	Type	Required	Meaning
`src`	text	yes	The audio file: a report-relative path or a data address.
`title`	text	yes	The player’s accessible name.
`caption`	text		The caption under the player.
`transcript`	report-folder file		A report-relative Markdown file shown under the player as its transcript.

Field	Type	Required	Default	Meaning
`src`	text	yes		The video file: a report-relative path or a data address.
`title`	text	yes		The player’s accessible name.
`caption`	text			The caption under the player.
`poster`	text			A poster image; without one the PDF prints a text card.
`transcript`	report-folder file			A report-relative Markdown file shown under the player as its transcript.
`captions`	report-folder file			A report-relative WebVTT file embedded as the video’s captions track.
`width`	whole number			The player width in pixels; a positive whole number.
`height`	whole number			The player height in pixels; a positive whole number.
`wide`	`true` or `false`		`false`	Whether the player takes the report’s full width instead of the text measure.

Scrollytelling keeps one image in view beside ordered steps:

Field	Type	Required	Default	Meaning
`title`	text			The heading of the scrollytelling element.
`chart`	any value			A chart as the figure, in place of `image`: the same keys as a chart block.
`image`	mapping			The one figure that stays in view beside the steps.
`image.src`	text	yes		The image file: a report-relative path or a data address.
`image.alt`	text			The text alternative.
`image.caption`	text			The caption under the figure.
`image.fit`	one of `contain`, `cover` or `fill`		`contain`	How the image fills its box.
`image.width`	whole number			The image width in pixels; a positive whole number.
`image.height`	whole number			The image height in pixels; a positive whole number.
`image.color`	any value			A #rrggbb colour that fills the box until the photo loads.
`image.credit`	mapping			The photographer’s credit; an Unsplash photo needs one.
`image.credit.author`	text			The photographer’s name.
`image.credit.author_url`	text			The photographer’s page.
`image.credit.source`	text			The photo’s source.
`image.credit.source_url`	text			The source’s address.
`steps`	list of mapping	yes		The narrative steps, in reading order.
`steps[n].text`	inline Markdown	yes		The step’s text.
`steps[n].title`	text			The step’s heading.
`steps[n].view`	mapping			The part of the image shown when the step scrolls in: x and y as fractions of the image, and a zoom of at least 1.
`steps[n].view.x`	number		`0`	The view’s left edge, as a fraction of the image width from 0 to 1.
`steps[n].view.y`	number		`0`	The view’s top edge, as a fraction of the image height from 0 to 1.
`steps[n].view.zoom`	number		`1`	How far the view zooms in, from 1 (the whole image) to 20.
`steps[n].state`	mapping			For a chart figure: the control options the step sets, as control id to option value.
`steps[n].highlight`	mapping			A box on the image, as x, y, w and h fractions.
`steps[n].highlight.x`	number	yes		The box’s left edge, as a fraction of the image width.
`steps[n].highlight.y`	number	yes		The box’s top edge, as a fraction of the image height.
`steps[n].highlight.w`	number	yes		The box’s width, as a fraction of the image width.
`steps[n].highlight.h`	number	yes		The box’s height, as a fraction of the image height.

External assets are diagnosed, and _richview.offline is false while resources remain external. Unsafe media and link protocols are removed or replaced with visible blocked output. Raw HTML never renders (see Markdown extensions).