eleventy-plugin-youtube-embed

\

This Eleventy plugin automatically embeds responsive YouTube videos from URLs in Markdown files. It’s part of the eleventy-plugin-embed-everything project.

- ⚡️ Installation
- 🛠 Usage
- ⚙️ Settings
- ⚠️ Notes and caveats

---

⚡️ Installation

In your Eleventy project, install the plugin through npm:

``sh
$ npm i eleventy-plugin-youtube-embed
`

Then add it to your Eleventy config file:

`javascript
// require the package at the top of the file with all the others
const embedYouTube = require("eleventy-plugin-youtube-embed");

module.exports = function(eleventyConfig) {

// There could be quite a lot of surrounding code here...

eleventyConfig.addPlugin(embedYouTube);

// There could be quite a lot of surrounding code here...

};
`


🛠 Usage

To embed a YouTube video into any Markdown page, paste its URL into a new line. The URL should be the only thing on that line.

$3

`markdown
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam vehicula, elit vel condimentum porta, purus.

https://www.youtube.com/watch?v=dQw4w9WgXcQ

Maecenas non velit nibh. Aenean eu justo et odio commodo ornare. In scelerisque sapien at.
`

$3

!Rick Astley performing “Never gonna give you up”

⚙️ Settings

You can configure the plugin to change its behavior by passing an options object to the addPlugin function:

`javascript
eleventyConfig.addPlugin(embedYouTube, {
// just an example, see default values below:
embedClass: 'my-alternate-classname'
});
`

$3

The plugin’s default settings reside in lib/defaults.js. All of these values can be changed with an options object passed to the plugin.

$3

You can use the Lite YouTube Embed instead of the standard YouTube iframe. In many circumstances this is a performance win because it delays loading the iframe element until the user clicks play.

Be aware that the Lite version defaults to loading two files from the jsDelivr CDN. It loads these files once on any HTML page that includes an embed. You can override both resource URIs if you want to load from a different source, such as unpkg or your own server.

In addition, using the Lite version will cause several of the plugin’s settings to become un-configurable. The embedClass option will still work, but the following options will be ignored if you set lite: true:

- allowAttrs
- allowAutoplay
- allowFullscreen
- lazy
- noCookie
- title (but titleOptions.download works)

#### Lite embed options

To use the default Lite version, simply pass lite: true to the options object when you add the plugin to your Eleventy config:

`javascript
eleventyConfig.addPlugin(embedYouTube, {
lite: true
});
`

#### Showing titles in Lite mode

✨ Added in 1.13.0

By default, Lite embeds don't display a title. As of v1.13.0, you can opt to download the video title from YouTube in Lite mode:

`javascript
eleventyConfig.addPlugin(embedYouTube, {
lite: true,
titleOptions: {
download: true
}
});
`

This option works basically the same way it does for the default mode, with one exception: Lite mode always ignores the default title value, since using it would result in every embed having the same title. If fetching the title data from YouTube fails for any reason, the title is omitted.

#### Configuring lite embed options

To manually configure the Lite version, pass an options object to the lite setting instead of true:

`javascript
eleventyConfig.addPlugin(embedYouTube, {
lite: {
// Change settings here
}
});
`

$3

The plugin supports common YouTube URL variants as well. These should also work in your Markdown files.:

`markdown


youtube.com/watch?v=dQw4w9WgXcQ
www.youtube.com/watch?v=dQw4w9WgXcQ

http://www.youtube.com/watch?v=dQw4w9WgXcQ
https://www.youtube.com/watch?v=dQw4w9WgXcQ

https://www.youtube.com/watch?v=dQw4w9WgXcQ
https://youtube.com/watch?v=dQw4w9WgXcQ

https://youtu.be/dQw4w9WgXcQ

https://www.youtube.com/watch?v=LQaehcfXvK0&feature=youtu.be
https://www.youtube.com/watch?v=dQw4w9WgXcQ&list=RDdQw4w9WgXcQ&start_radio=1&t=1
`

If you really want to get into the weeds, inspect test/_inc/validUrls.js, which generates the comprehensive list of URL patterns that are explicitly tested. And if you run across a URL pattern that you think should work, but doesn’t, please file an issue!

⚠️ Notes and caveats

- This plugin is deliberately designed _only_ to embed videos when the URL is on its own line, and not inline with other text.
- To do this, it uses a regular expression to recognize YouTube video URLs. Currently these are the limitations on what it can recognize in a Markdown parser’s HTML output:
- The URL must be wrapped in a paragraph tag:


- It may also be wrapped in an anchor tag, (inside the paragraph): `
- The URL string may have whitespace around it
- I’ve tried to accommodate common variants (like short youtu.be links, for example), but there are conceivably valid YouTube URLs that wouldn’t get recognized. Please file an issue if you run into an edge case!
- This plugin uses transforms, so it alters Eleventy’s HTML output as it’s generated. It doesn’t alter the source Markdown.
- Right now it supports only single videos, not playlists.
- The embedded video is responsive, using the intrinsic aspect ratio method. It will expand to fill whatever horizontal space is available.
- The embed dimensions are currently hard-coded to a 16:9 aspect ratio.