Embedding images and videos in a post
2 July 2026 · #guide #images #video
This post is a demonstration and reference for putting media into an article. Everything here is plain Markdown (with a little inline HTML for captions and embeds) — no special components to import.
Images
Drop image files in public/ — a folder like public/images/blog/ keeps
things tidy — then reference them with the standard Markdown image syntax. The
path is absolute from the site root (it starts at /), and the text in the
brackets is the alt text:
Which renders as a full-width image with the site’s rounded border:
Adding a caption
Wrap the image in a <figure> and add a <figcaption> to caption it. Leave a
blank line around the Markdown image so it’s still processed as Markdown:
<figure>
<figcaption>Study for a larger seascape, 2024.</figcaption>
</figure>
Self-hosted video
For a video file you host yourself, put the file in public/ (e.g.
public/videos/) and use a plain <video> tag. controls shows the play bar;
add muted loop autoplay playsinline instead if you want a silent background
clip. Always set a poster image so there’s something to see before it plays:
<video src="/videos/process.mp4" poster="/images/blog/process-poster.jpg" controls>
</video>The video scales to the column width automatically.
YouTube & Vimeo embeds
Use the platform’s embed URL in an <iframe> (on YouTube: Share → Embed).
A bare <iframe> is automatically sized to a responsive 16:9 box:
<iframe
src="https://www.youtube-nocookie.com/embed/aqz-KE-bpKQ"
title="Big Buck Bunny"
allow="accelerometer; clipboard-write; encrypted-media; picture-in-picture"
allowfullscreen
></iframe>Tip: youtube-nocookie.com is YouTube’s privacy-friendly embed domain.
A different aspect ratio
If an embed isn’t 16:9, wrap it in <div class="embed"> and set a --ratio.
The iframe then fills the box exactly:
<div class="embed" style="--ratio: 4 / 3">
<iframe src="…" title="…" allowfullscreen></iframe>
</div>