How I embed videos in notes now

• Aug 13, 2026 at 22:12 IST
• 2 min (246 words)
• coding· 11ty· ffmpeg

Every video on this site now lives next to the note that uses it, the same way images do. I drop a video into the note folder, reference it with one shortcode line, and pnpm ready handles the rest – transcoding, thumbnail/poster, upload, and the player.

1. Drop the recording into the note folder, like content/raw/some-note/demo.mov
2. Reference the mp4 name in the note, even when the dropped file is a .mov

{% video "./demo.mp4" %}

3. Running pnpm ready transcodes the file to an optimized web-ready MP4 (H.264, yuv420p, faststart, crf 26, width capped at 1600px), extracts a poster frame from about 25% in as demo-poster.webp, records state in _data/cache/video-cache.json, and uploads the mp4 and poster to R2 under raw/some-note/ folder.

The above shortcode attaches the poster automatically, the player loads nothing until someone presses play, and nothing is fetched from a third party. I used to do this by hand and wrote down the ffmpeg commands earlier, but now it's all automatic.

Also, a few things worth knowing:

• If I place my own demo-poster.webp next to the video, the pipeline keeps it instead of generating one
• Videos are gitignored like images, so recordings never reach the repository
• To reprocess a video, run node scripts/process-videos.js --force again
• The whole thing runs through ffmpeg, which keeps surprising me with what it can do

The first video I published this way is the demo in my whimsical Pi extension note, showing the rotating status phrases while Pi works.