Embed video in Markdown: pandoc output for mp4 and mp3

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 ![Doe Holdings demo](demo.mp4) 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:

cat vid.md vid-inline.md aud.md vid-html.md img.md

![Doe Holdings demo](demo.mp4)
Watch ![Doe Holdings demo](demo.mp4) before the call.
![Jane Doe voice note](note.mp3)
<video src="demo.mp4" controls></video>
![Doe Holdings logo](logo.png)

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:

pandoc -f commonmark -t html vid.md

<p><video src="demo.mp4" controls=""><a href="demo.mp4">Doe Holdings
demo</a></video></p>

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:

pandoc -f markdown -t html vid.md

<figure>
<video src="demo.mp4" controls=""><a href="demo.mp4">Doe Holdings
demo</a></video>
<figcaption aria-hidden="true">Doe Holdings demo</figcaption>
</figure>

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 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.

The same image line inside a sentence

In vid-inline.md the image sits between "Watch" and "before the call." The command:

pandoc -f markdown -t html vid-inline.md

<p>Watch <video src="demo.mp4" controls=""><a href="demo.mp4">Doe
Holdings demo</a></video> before the call.</p>

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:

pandoc -f commonmark -t html aud.md

<p><audio src="note.mp3" controls=""><a href="note.mp3">Jane Doe voice
note</a></audio></p>

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:

<figure>
<audio src="note.mp3" controls=""><a href="note.mp3">Jane Doe voice
note</a></audio>
<figcaption aria-hidden="true">Jane Doe voice note</figcaption>
</figure>

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:

pandoc -f markdown -t html vid-html.md

<video src="demo.mp4" controls>
</video>

From commonmark came <p><video src="demo.mp4" controls></video></p>.

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.

A png file name as a control

To compare against the media runs, img.md names logo.png. Under commonmark, pandoc printed:

<p><img src="logo.png" alt="Doe Holdings logo" /></p>

Under markdown, it printed:

<figure>
<img src="logo.png" alt="Doe Holdings logo" />
<figcaption aria-hidden="true">Doe Holdings logo</figcaption>
</figure>

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 '<video' vid.html printed 1, and grep -c '<img' vid.html printed 0.
5. Run a control on an image file. pandoc -f commonmark -t html img.md -o img.html exited with code 0. Counting with grep -c '<img' img.html printed 1, while grep -c '<video' img.html printed 0.
6. Check the inner link. grep -c 'href="demo.mp4"' vid.html printed 1.
7. Look for a figure. pandoc -f markdown -t html vid.md -o vid-md.html exited with code 0. Counting with grep -c '<figure>' 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, the help pages and the roadmap for where each part stands.

More at sashmark.com.