{% asset %}

Attributes

Parameter	Type	Required	Description
type	enum	✓	Media type: audio | video | image | html — determines the player or renderer
embed	enum	✓	show = inline player/image; link = clickable link with type icon
src	string	✓	URL, site-relative path (/assets/...), or relative path (./file.png)
alt	string	—	Alt text — required for images when embed=show, optional otherwise
caption	string	—	Caption displayed below the rendered asset
width	string	—	CSS max-width constraint (e.g. 80%, 400px) — defaults to 100%
align	enum	—	Horizontal alignment: left | center | right — defaults to center for show, left for link

Valid Parent Contexts

This tag is valid inside: {% article %}

Rules

Rule	Force	Realm	Reference	Description
asset-no-autoplay	must	global	—	Autoplay is never emitted for any asset type — not for video, not for audio. Only is used. renderingaccessibility
asset-video-aspect-ratio	must	global	—	All video embeds (iframe and native) are wrapped in a responsive container. Width is controlled by the attribute. rendering
asset-unknown-platform-fallback	must	global	—	If a video URL is from an unrecognised platform that requires proprietary JavaScript, the component falls back to behaviour and the compiler emits a warning. rendering
asset-audio-max-width	must	global	—	Audio players are sized to . No custom waveform player — only native HTML5 . rendering
asset-local-path-convention	should	global	—	Use relative paths for local assets — the compiler resolves them to . Store files at matching the article's frontmatter . conventionauthoring

\{% asset %\} is always self-closing (/%\}).

Rendering by type and embed mode

type	embed=show	embed=link
image	<img> wrapped in <figure> with optional caption	Thumbnail + file name link
video	YouTube/Vimeo → <iframe> embed; local → <video>	Play icon + title link
audio	HTML5 <audio controls> player	Headphone icon + file name link
html	Button opens modal dialog with iframe	Icon + title link (new tab)

Astro component: ArticleAsset.astro

Video platform detection

YouTube (youtube.com/watch?v=ID, youtu.be/ID) and Vimeo (vimeo.com/ID) URLs are detected automatically and rendered as responsive <iframe> embeds with allowfullscreen and loading="lazy". All other video URLs render as native <video controls preload="metadata">.

URL handling and path resolution

Prefix	Meaning	Resolution
https:// / http://	External URL	Hotlinked as-is
/assets/...	Site-relative	Served from Astro public/
./filename.png	Relative	Rewritten at compile time to /assets/articles/\{article-id\}/filename.png

YouTube video embedded inline with caption

tagassetvideo asset-tag-video-youtube

{% asset type="video" embed="show" src="https://www.youtube.com/watch?v=abc123"
         caption="Product walkthrough" width="80%" align="center" /%}

Local image embedded inline with alt and width

tagassetimage asset-tag-image-show

{% asset type="image" embed="show" src="./sketch-v2.png"
         alt="Architecture sketch v2" align="center" width="70%" /%}

Audio file as a clickable link

tagassetaudio asset-tag-audio-link

{% asset type="audio" embed="link" src="./interview-recording.mp3" /%}

Image as a clickable link with alt text

tagassetimage asset-tag-image-link

{% asset type="image" embed="link" src="./nvc-diagram.png" alt="NVC four-step process" /%}

HTML page opened in a modal dialog

tagassethtml asset-tag-html-show

{% asset type="html" embed="show" src="/_assets/authentic-relating/exercise-i-wish.html"
         caption="I Wish Exercise" /%}

HTML page as a clickable link

tagassethtml asset-tag-html-link

{% asset type="html" embed="link" src="/_assets/authentic-relating/ar-games-compendium.html"
         caption="AR Games Compendium" /%}