@gotfeedback/markdown-it-media
v1.0.1
Published
Markdown it plugin with rich media support, including video and audio.
Downloads
136
Maintainers
Readme
Plugin provides a special handling of video and audio and outputs them as
<video>
and <audio>
html elements respectively. Additional attributes are
also provided:
- Media size:
=WxH
(see @mdit/img-size). - Multiple sources:
![media/type](/path/to/alt-media.mp4)
. - Thumbnails:
#=/path/to/poster.jpeg
. - Captions:
[lang](/path/to/captions.lang.vtt)
.
This plugin uses the normal image syntax for all media types, and looks at the
extensions of the URL to determine whether to output <img>
, <audio>
, or
<video>
elements. This is similar to
markdown-it-html5-media. If the extension is missing
or unknown, we default to <img>
.
Installation
npm install @gotfeedback/markdown-it-media
Usage
import markdownIt from "markdown-it";
import markdownItMedia from "@gotfeedback/markdown-it-media";
// optional (with defaults)
const options = {
controls: false,
attrs: {
image: {},
audio: {},
video: {},
},
};
const md = markdownIt().use(markdownItMedia, options);
md.render("![Small Image](image.jpeg =85x50)");
<p>
<img src="image.jpeg" alt="Small Image" width="85" height="50" />
</p>
md.render("![Funny Clip](my-video.mp4)");
<p>
<video>
<source src="my-video.mp4" />
Funny Clip <a href="my-video.mp4">Download video</a>.
</video>
</p>
Options
Controls
Enable controls with controls
(default false
).
const md = markdownIt().use(markdownItMedia, { controls: true });
md.render("![](my-video.webm)");
<p>
<video controls>
<source src="my-video.webm" />
<a href="my-video.webm">Download video</a>.
</video>
</p>
Attrs
You can add arbitrary attributes to image, audio, or video using the attrs
option:
const md = markdownIt().use(markdownItMedia, {
attrs: {
image: { lazy: "true" },
video: { crossorigin: "anonymous", autoplay: "autoplay", muted: "muted" },
audio: { crossorigin: "anonymous", preload: "metadata", controls: "true" },
},
});
md.render(`
![](image.webp)
![](video.webm)
![](![audio/webm](audio.webm))
`);
<p>
<img src="image.webp" lazy="true" />
<video crossorigin="anonymous" autoplay="autoplay" muted="muted">
<source src="video.webm" />
<a href="video.webm">Download video</a>.
</video>
<audio crossorigin="anonymous" preload="metadata" controls="true">
<source src="audio.webm" type="audio/webm" />
<a href="audio.webm">Download audio</a>.
</audio>
</p>
Media Size
Use the =WxH
syntax to specify the width and height of the image, audio, or
video. Either the width or height can be omitted, but not the literal x
between them. In other words, you can specify only 800 px width with =800x
or
only 600 px height with =x600
.
The size attribute must come after the optional title.
![](image.jpeg "Title" =800x600)
<img src="image.jpeg" title="Title" width="800" height="600" />
![](image.jpeg =800x)
<img src="image.jpeg" width="800" />
![](image.jpeg =x600)
<img src="image.jpeg" height="600" />
Multiple Sources / Explicit Media Type
For audio or video You can replace the source or add additional sources using
the ![media/type](/path/to/media.ext)
syntax in place or after the source.
Additional sources must come before the optional title.
![Description](/video.webm ![video/mpeg](/path/to/alt-video.mp4) "optional title")
![Description](![video/webm](video.webm) ![video/mpeg](/path/to/alt-video.mp4) "optional title")
The using explicit media source can be handy if you are referencing a video or audio wich doesn’t have a matching file extension.
![Description](<![video/webm](/path/to/video)> "optional title")
![webm audio file](<![audio/webm](/path/to/audio.webm)%3E> "optional title")
Note: Additional sources or explicit media types are ignored for images.
Thumbnails
Thumbnails (or poster) can be added to a video or audio using the
#=/path/to/poster.jpeg
syntax.
The thumbnail attribute must come after the optional title.
![](video.webm "Title" #=thumbnail.jpeg)
<video poster="thumbnail.jpeg">
<source src="image.jpeg" />
</video>
Note: If you add a thumbnail to an audio, it will result in a <video>
element.
![An audio with thumbnail](song.mp3 #=album-cover.jpeg)
<video poster="album-cover.jpeg">
<source src="song.mp3" />
<!-- ... -->
</video>
Captions
Captions can be added to audio or video using the ![lang](path/to/caption.vtt
"Captions Label")
. [lang]
is a language
tag e.g. [zh]
for Chinese,
[en-US]
for US English, or [es-005]
for Latin American Spanish. The source
URL must be a .vtt
file.
You can add multiple captions and the caption attribute must come after the optional title:
![](video.webm "Title" ![zh](chinese-captions.vtt) ![en](english-captions.vtt))
<video title="Title">
<source src="video.webm" />
<track src="chinese-captions.vtt" srclang="zh" kind="captions" />
<track src="english-captions.vtt" srclang="en" kind="captions" />
<!-- ... -->
</video>
Captions can also be labelled:
![](video.webm "Title" ![en](captions.vtt "Caption Label"))
<video title="Title">
<source src="video.webm" />
<track
src="captions.vtt"
srclang="en"
label="Caption Label"
kind="captions"
/>
<!-- ... -->
</video>
Note: If you add captions to an audio, it will result in a <video>
element.
![An audio with captions](song.mp3 [en](lyrics.vtt "Show Lyrics"))
<video>
<source src="song.mp3" />
<track src="lyrics.vtt" srclang="en" label="Show Lyrics" />
<!-- ... -->
</video>
Examples
An Image with a width of 200 px and auto height:
![Image description](/path/to/image.png "some title" =200x)
<img alt="Image description" title="some title" width="200" />
An audio:
![Audio description](/path/to/audio.mp3)
<audio>
<source src="/path/to/audio.mp3" />
Audio description
<a href="/path/to/audio.mp3">Download audio</a>.
</audio>
A video with a width of 800 px and height of 600 px:
![Video description](/path/to/video.webm =800x600)
<video width="800" height="600">
<source src="/path/to/video.webm" />
Video description
<a href="/path/to/video">Download audio</a>.
</video>
A webm video with an alternative mp4 source:
![video description](![video/webm](/movie.webm) ![video/mpeg](/movie.mp4))
<video>
<source src="/movie.webm" type="video/webm" />
<source src="/movie.mp4" type="video/mpeg" />
video
<a href="/movie.webm">Download webm video</a>
<a href="/movie.mp4">Download mpeg video</a>.
</video>
Video with a poster:
![Video description](/path/to/video.webm #=/path/to/poster.jpeg)
<video poster="/path/to/poster.jpeg">
<source src="/path/to/video.webm" />
Video description
</video>
Video with english and arabic subtitles:
![Video description](/path/to/video.webm [en](/path/to/captions.en.vtt) [ar](/path/to/captions.ar.vtt))
<video>
<source src="/path/to/video.webm" />
<track kind="captions" src="/path/to/captions.en.vtt" srclang="en" />
<track kind="captions" src="/path/to/captions.ar.vtt" srclang="ar" />
Video description
</video>
Video with thumbnail, a poster, and a webm backup source
![Video with thumbnail, a poster, subtitles, and a webm backup source](
my-video.mp4
![video/webm](my-video.webm)
"optional title"
=800x600
#=thumbnail.jpeg
[en](captions.en.vtt "English")
[ar](captions.ar.vtt "Arabic")
)
<video title="optional title" width="800" height="600" poster="thumbnail.jpeg">
<source src="my-video.mp4" />
<source src="my-video.webm" type="video/webm" />
<track src="captions.en.vtt" srclang="en" label="English" kind="captions" />
<track src="captions.ar.vtt" srclang="ar" label="Arabic" kind="captions" />
Video with thumbnail, a poster, subtitles, and a webm backup source
<a href="my-video.mp4">Download video</a>
<a href="my-video.webm">Download webm video</a>.
</video>
Greatly inspired by markdown-it-html5-media and @mdit/img-size