Static sites don’t have to mean static content. With HTML5 and a few clever Jekyll includes, you can embed rich media that rivals any CMS-powered blog.

Vintage recording equipment

Audio Embeds

Adding audio to your posts is straightforward. Use the audio.html include:

{% include audio.html
   src="/assets/media/episode-01.mp3"
   title="Episode 01: Getting Started with Rails 8" %}

This renders a styled audio player with your custom title. The player respects the blog’s dark theme and fits seamlessly into the content flow.

Note: For production, consider hosting large media files on a CDN and referencing them by URL rather than bundling them with your site.

Video Embeds

YouTube Videos

Embedding a YouTube video is just as clean:

{% include video.html id="dQw4w9WgXcQ" %}

The include wraps the iframe in a responsive 16:9 container, so it looks great on every screen size.

Vimeo Support

Switch to Vimeo by adding the provider parameter:

{% include video.html id="123456789" provider="vimeo" %}

Self-Hosted Video

Got your own video files? Use the src parameter instead:

{% include video.html
   src="/assets/media/demo.mp4"
   poster="/assets/images/demo-poster.jpg" %}

The Responsive Container

The secret sauce is a simple CSS aspect-ratio trick:

.video-container {
  position: relative;
  width: 100%;
  padding-bottom: 56.25%; /* 16:9 */
  height: 0;
  border-radius: var(--radius);
  overflow: hidden;
}

.video-container iframe,
.video-container video {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
}

This ensures your video always maintains the correct aspect ratio, whether it’s on a 4K monitor or a phone screen.

Accessibility Considerations

When embedding media, always consider:

  1. Provide fallback text — The <audio> and <video> tags support fallback content for browsers that don’t support them
  2. Use preload="metadata" — This loads only the essential metadata without downloading the full file
  3. Add poster images for videos — Gives users context before they hit play
  4. Consider captions — Use <track> elements for subtitle support
<video controls preload="metadata">
  <source src="/assets/media/talk.mp4" type="video/mp4">
  <track kind="captions" src="/assets/media/talk.vtt"
         srclang="en" label="English">
  Your browser does not support the video tag.
</video>

Performance Tips

Media files can bloat your static site. Here are some strategies:

FFmpeg

Raw Video

H.264 / AAC

WebM Fallback

MP4 Primary

Cloudflare R2
  • Lazy load iframes with loading="lazy" attribute
  • Compress video with tools like ffmpeg:
ffmpeg -i input.mp4 -vcodec libx264 -crf 28 \
       -preset medium -acodec aac -b:a 128k \
       output.mp4
  • Use WebM format alongside MP4 for better compression
  • Host large files externally — S3, Cloudflare R2, or a CDN

The best blogs aren’t just read — they’re experienced. Audio and video bring ideas to life in ways that text alone cannot.