+++ title = “Shortcodes” weight = 40 +++
While Markdown is good at writing, it isn't great when you need write inline HTML to add some styling for example.
To solve this, Gutenberg borrows the concept of shortcodes
from WordPress.
In our case, the shortcode corresponds to a template that is defined in the templates/shortcodes
directory or a built-in one.
Let's write a shortcode to embed YouTube videos as an example.
In a file called youtube.html
in the templates/shortcodes
directory, paste the
following:
<div {% if class %}class="{{class}}"{% endif %}>
<iframe
src="https://www.youtube.com/embed/{{id}}{% if autoplay %}?autoplay=1{% endif %}"
webkitallowfullscreen
mozallowfullscreen
allowfullscreen>
</iframe>
</div>
This template is very straightforward: an iframe pointing to the YouTube embed URL wrapped in a <div>
.
In terms of input, it expects at least one variable: id
. Since the other variables
are in a if
statement, we can assume they are optional.
That's it, Gutenberg will now recognise this template as a shortcode named youtube
(the filename minus the .html
extension).
There are two kinds of shortcodes: ones that do no take a body like the YouTube example above and ones that do, a quote for example. In both cases, their arguments must be named and they will all be passed to the template.
Do note that shortcodes in code blocks will be ignored.
Those look like rendering a variable in Tera.
On a new line, call the shortcode as if it was a function in a variable block. All the examples below are valid calls of the YouTube shortcode.
{{ youtube(id="dQw4w9WgXcQ") }}
{{ youtube(id="dQw4w9WgXcQ", autoplay=true) }}
{{ youtube(id="dQw4w9WgXcQ", autoplay=true, class="youtube") }}
Those look like a block in Tera.
For example, let's imagine we have the following shortcode quote.html
template:
<blockquote>
{{ body }} <br>
-- {{ author}}
</blockquote>
We could use it in our markup file like so:
{% quote(author="Vincent") %}
A quote
{% end %}
The body
variable used in the shortcode template will be implicitly passed down to the rendering
context automatically.
Gutenberg comes with a few built-in shortcodes. If you want to override a default shortcode template,
simply place a {shortcode_name}.html
file in the templates/shortcodes
directory and Gutenberg will
use that instead.
Embed a responsive player for a YouTube video.
The arguments are:
id
: the video id (mandatory)class
: a class to add the div
surrounding the iframeautoplay
: whether to autoplay the video on loadUsage example:
{{ youtube(id="dQw4w9WgXcQ") }}
{{ youtube(id="dQw4w9WgXcQ", autoplay=true) }}
{{ youtube(id="dQw4w9WgXcQ", autoplay=true, class="youtube") }}
Result example:
{{ youtube(id="dQw4w9WgXcQ”) }}
Embed a player for a Vimeo video.
The arguments are:
id
: the video id (mandatory)class
: a class to add the div
surrounding the iframeUsage example:
{{ vimeo(id="124313553") }}
{{ vimeo(id="124313553", class="vimeo") }}
Result example:
{{ vimeo(id="124313553”) }}
Embed a player for a Streamable video.
The arguments are:
id
: the video id (mandatory)class
: a class to add the div
surrounding the iframeUsage example:
{{ streamable(id="2zt0") }}
{{ streamable(id="2zt0", class="streamble") }}
Result example:
{{ streamable(id="2zt0”) }}
Embed a Github gist.
The arguments are:
url
: the url to the gist (mandatory)file
: by default, the shortcode will pull every file from the URL unless a specific filename is requestedclass
: a class to add the div
surrounding the iframeUsage example:
{{ gist(id="https://gist.github.com/Keats/e5fb6aad409f28721c0ba14161644c57") }}
{{ gist(id="https://gist.github.com/Keats/e5fb6aad409f28721c0ba14161644c57", class="gist") }}
Result example:
{{ gist(url="https://gist.github.com/Keats/e5fb6aad409f28721c0ba14161644c57”) }}