Grav YouTube Plugin

YouTube is a simple Grav Plugin that converts markdown links into responsive embeds.

Installation

Installing the YouTube plugin can be done in one of two ways. Our GPM (Grav Package Manager) installation method enables you to quickly and easily install the plugin with a simple terminal command, while the manual method enables you to do so via a zip file.

GPM Installation (Preferred)

The simplest way to install this plugin is via the Grav Package Manager (GPM) through your system's Terminal (also called the command line). From the root of your Grav install type:

bin/gpm install youtube

This will install the YouTube plugin into your /user/plugins directory within Grav. Its files can be found under /your/site/grav/user/plugins/youtube.

Manual Installation

To install this plugin, just download the zip version of this repository and unzip it under /your/site/grav/user/plugins. Then, rename the folder to youtube. You can find these files either on GitHub or via GetGrav.org.

You should now have all the plugin files under

/your/site/grav/user/plugins/youtube

Config Defaults

enabled: true
built_in_css: true
add_editor_button: true
editor_insert_mode: link
player_parameters:
  autoplay: 0
  cc_load_policy: 0
  color: red
  controls: 1
  disablekb: 0
  enablejsapi: 0
  fs: 1
  hl: ''
  iv_load_policy: 1
  loop: 0
  modestbranding: 0
  origin: ''
  playsinline: 0
  rel: 1
  vq: default
privacy_enhanced_mode: true

If you need to change any value, then the best process is to copy the youtube.yaml file into your users/config/plugins/ folder (create it if it doesn't exist), and then modify there. This will override the default settings.

You can also set any of these settings on a per-page basis by adding them under a youtube: setting in your page header. For example:

---
title: YouTube Video
youtube:
    player_parameters:
        autoplay: 1
---

[plugin:youtube](https://www.youtube.com/watch?v=BK8guP9ov2U)

This will display a video and auto-play it.

For more details on the player_parameters, please check out the YouTube official documentation

Usage

To use this plugin you simply need to include a youtube URL in markdown link such as:

[plugin:youtube](https://www.youtube.com/watch?v=BK8guP9ov2U)

Will be converted into the following embeded HTML:

<div class="grav-youtube-wrapper"><div class="grav-youtube"><iframe title="YouTube video player" src="https://www.youtube.com/embed/BK8guP9ov2U" frameborder="0" allowfullscreen=""></iframe></div></div>

CSS is also loaded to provide the appropriate responsive layout.

Shortcode Syntax

As of version 3.0 you can now use an alternative shortcode syntax that supports passing in the player parameter values inline.

NOTE: shortcode-core plugin is required and must be installed and enabled for Shortcode Syntax to work.

[youtube color=white autoplay=1]https://www.youtube.com/watch?v=BK8guP9ov2U[/youtube]

Using the shortcode syntax it is also possible to set a custom thumbnail picture when using lazy_load.

[youtube lazy_load=true thumbnail="name of media.jpg"]https://www.youtube.com/watch?v=BK8guP9ov2U[/youtube]

Parameter routing

Shortcode attributes are routed to one of three destinations based on what they are, so a setting only ever ends up where it belongs:

• YouTube player parameters (autoplay, rel, controls, start, loop, etc.) are appended to the embed URL sent to YouTube. See the YouTube official documentation for the full list.
• Plugin settings (privacy_enhanced_mode, lazy_load, class, thumbnail) are handled by the plugin and are never added to the URL.
• iframe attributes (width, height, title, and any other attribute) are rendered directly on the <iframe> element.

This means a plugin setting such as privacy_enhanced_mode no longer leaks into the YouTube URL, and sizing or accessibility attributes apply to the iframe itself:

[youtube width=640 height=360 title="Intro video" privacy_enhanced_mode=true rel=0]https://www.youtube.com/watch?v=BK8guP9ov2U[/youtube]

Accessibility

Every embed includes a title attribute on the iframe, which screen readers announce in place of the video. It defaults to YouTube video player; set your own with the title shortcode attribute (or the Title field in the Editor Pro dialog) to describe the specific video.

Editor Button

The plugin adds a YouTube button to the page content editor. Click it, paste a video URL, and the embed code is inserted for you. Turn the button off with add_editor_button: false. The button appears in:

• Admin 1 — the classic markdown editor toolbar.
• Admin 2 — both the default (CodeMirror) markdown editor toolbar and the Editor Pro toolbar.

Insert mode

The editor_insert_mode setting controls what the button inserts:

• link (default) — inserts a built-in [plugin:youtube](url) link. This is rendered by the YouTube plugin on its own and needs no other plugins.
• shortcode — inserts a [youtube]...[/youtube] shortcode with the full set of player options exposed as form fields. This format requires the separate shortcode-core plugin to render. If shortcode-core isn't enabled, the button falls back to the built-in link so it always works.

In Admin 2 the button is provided through the Editor Pro plugin's toolbar; in shortcode mode the YouTube shortcode is also registered with Editor Pro so it appears in the shortcode picker.