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
In your Eleventy project, install the plugin through npm:
$ npm i eleventy-plugin-youtube-embedThen add it to your Eleventy config file:
// `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...
};
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.
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.
You can configure the plugin to change its behavior by passing an options object to the addPlugin function:
eleventyConfig.addPlugin(embedYouTube, {
// just an example, see default values below:
embedClass: 'my-alternate-classname'
});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.
| Option | Type | Default value |
Notes |
allowAttrs |
String | accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture |
Default allow attributes that get applied to the embed iframe. Substitute your preferred string to allow other iframe behaviors and feature policies. |
allowAutoplay |
Boolean | false |
Setting this to true will cause all embedded videos to autoplay. Be cool: don’t do it! |
allowFullscreen |
Boolean | true |
Default allowfullscreen attribute that gets applied to the embed iframe. Changing this to false will disable the fullscreen button on your embeds. |
embedClass |
String | eleventy-plugin-youtube-embed |
Class name applied to the div element that wraps the embedded YouTube iframe. Use the default string to target the embeds with CSS, or substitute your preferred string. |
lazy |
Boolean | false |
Setting this to true will add a loading="lazy" attribute to the standard iframe embed. Some browsers will use this to optimize resource loading. |
lite |
Boolean or Object | false |
Setting this to true will use Paul Irish’s Lite YouTube Embed method. See the section on the Lite version below for more details. |
modestBranding |
Boolean | false |
Setting this to true will add a modestbranding=1 attribute to the embed url. This will tell YouTube to show minimal YouTube branding |
noCookie |
Boolean | true |
Defaults to the “privacy-enhanced” www.youtube-nocookie.com domain. Change this to false to use www.youtube.com. |
recommendSelfOnly |
Boolean | false |
Setting this to true will add a rel=0 attribute to the embed url. This will tell YouTube to recommend videos from the same channel. |
title✨ New in v1.10.0! |
String | Embedded YouTube video |
Edit this value to change the default title attribute for the embedded iframe. |
titleOptions✨ New in v1.10.0! |
|||
titleOptions.download |
Boolean | false |
Setting this to true will download and cache the title of the video from YouTube, then override the default value of title. Note: Turning this feature on will cause a network call to YouTube’s servers. |
titleOptions.cacheDuration |
String | 5m |
The length of time to cache the data from YouTube when titleOptions.download is set to true. Use the cache duration syntax from @11ty/eleventy-fetch to set this value. |
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:
allowAttrsallowAutoplayallowFullscreenlazynoCookietitleandtitleOptions
To use the default Lite version, simply pass lite: true to the options object when you add the plugin to your Eleventy config:
eleventyConfig.addPlugin(embedYouTube, {
lite: true
});To manually configure the Lite version, pass an options object to the lite setting instead of true:
eleventyConfig.addPlugin(embedYouTube, {
lite: {
// Change settings here
}
});| Option | Type | Default value |
Notes |
lite.css.enabled |
Boolean | true |
If you change this to false, then the plugin won’t add any CSS to the page. You’ll need to handle loading the necessary CSS yourself. |
lite.css.inline |
Boolean | false |
If you change this to true, then the plugin will load the CSS inline in <style> tags, instead of using the default <link> tag. |
lite.css.path |
String | https://cdn.jsdelivr.net/gh/paulirish/[email protected]/src/lite-yt-embed.min.css |
Pass a custom URL to load the necessary CSS from the source of your choice. |
lite.js.enabled |
Boolean | true |
If you change this to false, then the plugin won’t add any JavaScript to the page. You’ll need to handle loading the necessary JavaScript yourself. |
lite.js.inline |
Boolean | false |
If you change this to true, then the plugin will load the JavaScript inline in <script> tags. |
lite.js.path |
String | https://cdn.jsdelivr.net/gh/paulirish/[email protected]/src/lite-yt-embed.min.js |
Pass a custom URL to load the necessary JavaScript from the source of your choice. |
lite.jsApi✨ New in v1.11.0! |
Boolean | false |
If you change this to true, then the plugin adds a `js-api` parameter to the custom element that enables access to YouTube's IFrame Player API. See usage example and demo. |
lite.responsive✨ New in v1.10.0! |
Boolean | false |
If you change this to true, then the plugin adds a CSS rule to override the default max-width of <lite-youtube> elements, which are hard coded to a maximum of 720 pixels. |
lite.thumbnailFormat✨ New in v1.11.0! |
String | jpg |
If you change this to webp, then the plugin will load the YouTube thumbnail image in WebP format instead of JPEG. |
lite.thumbnailQuality |
String | hqdefault |
Override the requested YouTube thumbnail image file. Accepted values are default, hqdefault, mqdefault, sddefault, maxresdefault. Note that not all sizes are available for all videos. If the requested resolution isn’t available, YouTube shows a generic placeholder instead. |
The plugin supports common YouTube URL variants as well. These should also work in your Markdown files.:
<!-- No protocol: -->
youtube.com/watch?v=dQw4w9WgXcQ
www.youtube.com/watch?v=dQw4w9WgXcQ
<!-- With or without HTTPS: -->
http://www.youtube.com/watch?v=dQw4w9WgXcQ
https://www.youtube.com/watch?v=dQw4w9WgXcQ
<!-- With or without 'www': -->
https://www.youtube.com/watch?v=dQw4w9WgXcQ
https://youtube.com/watch?v=dQw4w9WgXcQ
<!-- YouTu.be short-links: -->
https://youtu.be/dQw4w9WgXcQ
<!-- URLs with extra parameters: -->
https://www.youtube.com/watch?v=LQaehcfXvK0&feature=youtu.be
https://www.youtube.com/watch?v=dQw4w9WgXcQ&list=RDdQw4w9WgXcQ&start_radio=1&t=1If 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!
- 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:
<p> - It may also be wrapped in an anchor tag, (inside the paragraph):
<a> - The URL string may have whitespace around it
- The URL must be wrapped in a paragraph tag:
- 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.