Skip to content

Rendering videos from Markdown

Widely compatibleRendering:Prerendered: WorksOn-demand: WorksAstro>=5.0.0

Out of the box, Astro turns every Markdown ![](...) node into an <img> tag regardless of its file extension:

  • A video in public/ (![Demo](/clip.mp4)) compiles to <img src="/clip.mp4" alt="Demo">, which browsers will not play.
  • A relative path into src/ (![Demo](./clip.mp4)) is even worse: Astro hands the file to its image optimization pipeline and the build fails with MissingImageDimension.

You can fix this either with inline HTML or by teaching Astro’s Markdown processor to emit <video> tags automatically.

Standard Markdown supports raw HTML directly. Place the video file in public/ (or host it on a CDN) and write a <video> element inline:

src/content/blog/demo.md
<video src="/clip.mp4" controls preload="metadata"></video>

If you only embed videos occasionally, inline HTML requires zero configuration and gives you full control over attributes like poster, muted, loop, playsinline, and <track> captions.

Option 2: Convert ![](*.mp4) automatically with a Markdown plugin

Section titled “Option 2: Convert ![](*.mp4) automatically with a Markdown plugin”

If you want authors or a CMS to keep using standard Markdown image syntax (![Demo clip](/clip.mp4)), write a small Markdown plugin that swaps video image nodes for raw <video> HTML.

Because user Markdown plugins run before Astro collects images for optimization, replacing the image node also prevents Astro from trying to process the video file as an image.

Astro 7 uses Sätteri as its default Markdown processor, so you can register a lightweight mdastPlugins visitor directly without installing extra packages:

src/lib/satteri-video.mjs
const VIDEO_EXT = /\.(mp4|webm|mov)(?:[?#].*)?$/i;
function escapeAttr(value) {
return value
.replace(/&/g, "&amp;")
.replace(/"/g, "&quot;")
.replace(/</g, "&lt;");
}
export const satteriVideo = {
name: "satteri-video",
image(node) {
if (!VIDEO_EXT.test(node.url)) return;
const src = escapeAttr(node.url);
const label = node.alt ? ` aria-label="${escapeAttr(node.alt)}"` : "";
return {
type: "html",
value: `<video src="${src}" controls preload="metadata"${label}></video>`,
};
},
};

Register the plugin in astro.config.mjs:

astro.config.mjs
import { satteri } from "@astrojs/markdown-satteri";
import { defineConfig } from "astro/config";
import { satteriVideo } from "./src/lib/satteri-video.mjs";
export default defineConfig({
markdown: {
processor: satteri({
mdastPlugins: [satteriVideo],
}),
},
});

Now Markdown image syntax pointing to a video file:

src/content/blog/demo.md
![Demo clip](/clip.mp4)

renders as:

<p><video src="/clip.mp4" controls preload="metadata" aria-label="Demo clip"></video></p>

while regular images (![Photo](./photo.png)) continue through Astro’s image pipeline untouched.

  • Store videos in public/ or on an external CDN: The plugin emits the URL verbatim inside an html node, so relative paths into src/ will not be bundled or copied into dist/.
  • Accessibility: Mapping Markdown alt text to aria-label gives screen readers a concise description, while longer videos with spoken content should include <track kind="captions"> via inline HTML or an MDX component.
  • Need richer video embeds? If you want custom poster frames, responsive containers, or captions without writing raw HTML in Markdown, consider MDX with a reusable <Video /> Astro component instead.

Compatibility

EnvironmentSupportVersion
Framework
AstroWorks>=5.0.0
RenderingAstro docs
PrerenderedWorksAny version
On-demandWorksAny version
Compatibility legend:Recommended — Best practiceWorks — SupportedDoesn't work — Unsupported