Rendering videos from Markdown
Widely compatibleRendering:Prerendered: WorksOn-demand: WorksAstro>=5.0.0
Works across all listed Astro environments.
Out of the box, Astro turns every Markdown  node into an <img> tag regardless of its file extension:
- A video in
public/() compiles to<img src="/clip.mp4" alt="Demo">, which browsers will not play. - A relative path into
src/() is even worse: Astro hands the file to its image optimization pipeline and the build fails withMissingImageDimension.
You can fix this either with inline HTML or by teaching Astro’s Markdown processor to emit <video> tags automatically.
Option 1: Write inline HTML (simplest)
Section titled “Option 1: Write inline HTML (simplest)”Standard Markdown supports raw HTML directly. Place the video file in public/ (or host it on a CDN) and write a <video> element inline:
<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  automatically with a Markdown plugin
Section titled “Option 2: Convert  automatically with a Markdown plugin”If you want authors or a CMS to keep using standard Markdown image syntax (), 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:
const VIDEO_EXT = /\.(mp4|webm|mov)(?:[?#].*)?$/i;
function escapeAttr(value) { return value .replace(/&/g, "&") .replace(/"/g, """) .replace(/</g, "<");}
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:
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], }), },});If your Astro 7 project uses the unified/remark processor, install @astrojs/markdown-remark and unist-util-visit:
npm i @astrojs/markdown-remark unist-util-visitpnpm add @astrojs/markdown-remark unist-util-visityarn add @astrojs/markdown-remark unist-util-visitbun add @astrojs/markdown-remark unist-util-visitdeno add @astrojs/markdown-remark unist-util-visitimport { visit } from "unist-util-visit";
const VIDEO_EXT = /\.(mp4|webm|mov)(?:[?#].*)?$/i;
function escapeAttr(value) { return value .replace(/&/g, "&") .replace(/"/g, """) .replace(/</g, "<");}
export function remarkVideo() { return (tree) => { visit(tree, "image", (node, index, parent) => { if (!parent || index === undefined || !VIDEO_EXT.test(node.url)) { return; } const src = escapeAttr(node.url); const label = node.alt ? ` aria-label="${escapeAttr(node.alt)}"` : ""; parent.children[index] = { type: "html", value: `<video src="${src}" controls preload="metadata"${label}></video>`, }; }); };}Register it through unified() in astro.config.mjs:
import { unified } from "@astrojs/markdown-remark";import { defineConfig } from "astro/config";import { remarkVideo } from "./src/lib/remark-video.mjs";
export default defineConfig({ markdown: { processor: unified({ remarkPlugins: [remarkVideo], }), },});Install unist-util-visit:
npm i unist-util-visitpnpm add unist-util-visityarn add unist-util-visitbun add unist-util-visitdeno add unist-util-visitCreate src/lib/remark-video.mjs using the same plugin code shown in the Astro 7 (Remark) tab, then register it in astro.config.mjs:
import { defineConfig } from "astro/config";import { remarkVideo } from "./src/lib/remark-video.mjs";
export default defineConfig({ markdown: { remarkPlugins: [remarkVideo], },});Now Markdown image syntax pointing to a video file:
renders as:
<p><video src="/clip.mp4" controls preload="metadata" aria-label="Demo clip"></video></p>while regular images () continue through Astro’s image pipeline untouched.
Things to keep in mind
Section titled “Things to keep in mind”- Store videos in
public/or on an external CDN: The plugin emits the URL verbatim inside anhtmlnode, so relative paths intosrc/will not be bundled or copied intodist/. - Accessibility: Mapping Markdown alt text to
aria-labelgives 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.
Source discussion
Section titled “Source discussion”Compatibility
| Environment | Support | Version |
|---|---|---|
| Framework | ||
| Astro | Works | >=5.0.0 |
| RenderingAstro docs | ||
| Prerendered | Works | Any version |
| On-demand | Works | Any version |