---
title: "Embed video in Markdown: pandoc output for mp4 and mp3"
slug: markdown-embed-video
excerpt: "Under An mp4 file name in image syntax, two readers' HTML for one image line naming demo.mp4 is quoted as printed."
quickAnswer: "Under The test files and two readers, the inputs and both reader names are listed. Output from two readers for one line naming demo.mp4 is quoted in An mp4 file name in image syntax. A sentence holding that same line is covered in The same image line inside a sentence. Runs on note.mp3 appear under An mp3 file name in image syntax. Pandoc's result for a tag spelled out by hand sits in A video tag typed as raw HTML. Pandoc's output for logo.png through both readers fills A png file name as a control. Seven numbered steps fill Check what pandoc wrote for your own file."
keyTakeaways:
- "Two readers' output for one image line naming demo.mp4 is quoted byte for byte under An mp4 file name in image syntax."
- "The section The same image line inside a sentence quotes what came back when words share the line."
- "Results for note.mp3 from both readers are set out in An mp3 file name in image syntax."
- "Both readers' output for a complete tag in the file appears in A video tag typed as raw HTML."
- "Counting commands for the HTML file are listed in Check what pandoc wrote for your own file."
publishedDate: 2026-10-21
dateModified: 2026-10-21
author: Bobby Huang
cluster: B
role: post
status: published
faq:
- q: Can I embed video in Markdown with image syntax?
a: "Pandoc's output for an image line naming demo.mp4 is quoted under An mp4 file name in image syntax."
- q: Why did my video line end up inside a figure?
a: "The section An mp4 file name in image syntax quotes the figure output and links the post that covers figures."
- q: Does a typed video tag come through conversion?
a: "Under A video tag typed as raw HTML, what both readers printed is quoted."
- q: Which commands confirm the element in my HTML?
a: "The commands sit, in order, under Check what pandoc wrote for your own file."
related:
- markdown-images
- markdown-image-size
- raw-html-in-markdown
---
One way to try to embed video in Markdown is to put a video file name where an image path goes. This post records the HTML pandoc wrote when the line `` went through two of its readers. It also records what changed for an `.mp3` name, for words placed around the image, and for a hand-built tag.
Every conversion here was done one time on a Mac by pandoc, which printed 3.8.3 as its version. What follows covers the printed HTML and stops there.
## The test files and two readers
Five one-line files sat in a test folder. This command printed them in order:
```sh
cat vid.md vid-inline.md aud.md vid-html.md img.md
```
```text
Watch  before the call.
```
The first file, vid.md, holds a lone image line whose path is demo.mp4. In vid-inline.md that same image sits between words of a sentence. The file aud.md names note.mp3. In vid-html.md a hand-typed tag replaces the image syntax. Last comes img.md, which names logo.png and acts as a control.
The folder held no demo.mp4, note.mp3 or logo.png. Running `ls demo.mp4 note.mp3 logo.png` printed a "No such file or directory" line for each name. Every pandoc run still exited with code 0.
Two readers, `markdown` and `commonmark`, took each file in turn. The reader name goes after `-f`, and the file name comes last.
## An mp4 file name in image syntax
Start with the `commonmark` reader:
```sh
pandoc -f commonmark -t html vid.md
```
```html
```
Pandoc wrote a `video` element. The path from the parentheses went into its `src` attribute, and the element carries `controls=""`. Inside the element sits an `a` element whose `href` names that same file. The words from the square brackets, Doe Holdings demo, became the text of that link. This output holds no `img` element and no `alt` attribute.
In this run, pandoc put the bracket text inside the link and wrote it into no attribute.
The line break after Holdings is part of pandoc's printed output. Both readers broke the text at that same spot for this file.
Now the `markdown` reader on that file:
```sh
pandoc -f markdown -t html vid.md
```
```html
Doe Holdings demo
```
The `video` element and its inner link match the `commonmark` result byte for byte. Around them, this reader wrapped a `figure` element. After the `video` element comes a `figcaption` holding the bracket text, marked `aria-hidden="true"`.
The [post on image width and figures](markdown-image-size.md) covers the pandoc extension `implicit_figures` and when pandoc wraps an image line in a figure. Bracket text and image paths each get a section in the [Markdown images guide](markdown-images.md).
## The same image line inside a sentence
In vid-inline.md the image sits between "Watch" and "before the call." The command:
```sh
pandoc -f markdown -t html vid-inline.md
```
```html
Watch before the call.
```
The `commonmark` reader matched that pair of lines exactly. With words on both sides, the `markdown` reader wrote a paragraph and left out the `figure`. The `video` element sits in the running text of the sentence, and its inner link and attributes are the ones from vid.md.
Here, then, the two readers split on the lone line and matched on the sentence. Among the media runs, the figure wrapping turned up for lone image lines under `markdown` and for no other run.
## An mp3 file name in image syntax
The file aud.md swaps in a different path and different bracket text. Under `commonmark`:
```sh
pandoc -f commonmark -t html aud.md
```
```html
```
Here pandoc wrote an `audio` element in the spot where vid.md got `video`. The rest kept the same shape. The path sits in `src`, the element carries `controls=""`, and an inner `a` element links to note.mp3 with the bracket text as its words.
Under `markdown`, this output came back:
```html
Jane Doe voice note
```
That matches the pattern from vid.md. A lone line under `markdown` got a `figure` and a `figcaption` with the bracket text.
Across the media files in this test, the element name lined up with the ending of the path. A name ending in `.mp4` gave `video`, and a name ending in `.mp3` gave `audio`. Other endings were not tried here, apart from the `.png` control below.
## A video tag typed as raw HTML
The file vid-html.md skips image syntax and holds a tag typed out in full. Under `markdown`:
```sh
pandoc -f markdown -t html vid-html.md
```
```html
```
From `commonmark` came ``.
The typed tag survived under both readers. The `markdown` reader put the closing tag on a separate line and added no paragraph. The `commonmark` reader kept the whole tag on one line and put it inside a `p` element.
Two more points stand out against the image syntax runs. The attribute `controls` stayed bare, as typed, with no `=""` after it. No inner `a` element appeared either; the typed tag held nothing between its opening and closing parts.
Raw tags, plus the rule about blank lines around them, have their own [post about raw HTML](raw-html-in-markdown.md).
## A png file name as a control
To compare against the media runs, img.md names logo.png. Under `commonmark`, pandoc printed:
```html
```
Under `markdown`, it printed:
```html
Doe Holdings logo
```
With a `.png` path, the bracket text landed in an `alt` attribute on an `img` element. In the `.mp4` and `.mp3` runs, that text became link words inside the element. The `figure` wrapping under `markdown` showed up for this file too.
## Check what pandoc wrote for your own file
These steps use cat, grep and pandoc. The numbers are the ones this test printed for its files.
1. Read the line. Run `cat vid.md` and confirm the path in the parentheses is the file name you meant.
2. Check the ending of the path. `grep -c '\.mp4)' vid.md` printed `1`.
3. Convert and save the HTML with your chosen reader. `pandoc -f commonmark -t html vid.md -o vid.html` exited with code 0.
4. Count the element. `grep -c '' vid-md.html` gave `1`, and the same count on vid.html gave `0`.
## Where Sashmark fits
Once Sashmark reaches its planned v1, a slipped word might get mended straight on the formatted page. Its planned Round-Trip, the clean kind, is meant to give back each line left untouched carrying its original bytes. Planned alongside it, a Changes View would highlight anything altered since your prior visit, without asking you to run git.
It is in development and has not been released. The app itself has no AI features. See the [planned features](/features), the [help pages](/help) and the [roadmap](/roadmap) for where each part stands.
More at [sashmark.com](https://www.sashmark.com/).
