2013-07-06 23:36:30 +00:00
---
2014-05-29 22:42:05 +00:00
aliases:
- /doc/shortcodes/
2016-02-03 13:45:21 +00:00
lastmod: 2016-02-03
2014-05-29 22:42:05 +00:00
date: 2013-07-01
2014-04-23 07:00:11 +00:00
menu:
main:
2014-05-29 22:42:05 +00:00
parent: extras
2015-01-26 13:56:26 +00:00
next: /extras/pagination
2014-05-29 22:42:05 +00:00
prev: /extras/permalinks
title: Shortcodes
2014-11-25 08:07:18 +00:00
weight: 80
2015-11-20 19:31:57 +00:00
toc: false
2013-07-08 21:57:01 +00:00
---
2013-07-04 15:32:55 +00:00
2015-01-28 02:17:09 +00:00
Hugo uses Markdown for its simple content format. However, there are a lot
2014-10-07 23:52:58 +00:00
of things that Markdown doesn’ t support well.
2013-07-04 15:32:55 +00:00
2014-02-18 23:35:03 +00:00
We are unwilling to accept being constrained by our simple format. Also
2014-10-07 23:52:58 +00:00
unacceptable is writing raw HTML in our Markdown every time we want to include
2014-02-18 23:35:03 +00:00
unsupported content such as a video. To do so is in complete opposition to the
2015-11-30 06:23:25 +00:00
intent of using a bare-bones format for our content and utilizing templates to
2014-02-18 23:35:03 +00:00
apply styling for display.
2013-07-04 15:32:55 +00:00
2014-10-07 23:52:58 +00:00
To avoid both of these limitations, Hugo created shortcodes.
2013-07-04 15:32:55 +00:00
2014-08-27 09:36:26 +00:00
A shortcode is a simple snippet inside a content file that Hugo will render
2014-10-07 23:52:58 +00:00
using a predefined template. Note that shortcodes will not work in template
files---if you need a functionality like that in a template, you most likely
2015-01-28 02:17:09 +00:00
want a [partial template ](/templates/partials/ ) instead.
2013-07-04 15:32:55 +00:00
2016-02-03 13:45:21 +00:00
Another benefit is, you can update your shortcode with any related new classes or
techniques, and upon generation, Hugo will easily merge in your changes. You
avoid a possibly complicated search and replace operation.
2014-02-18 23:35:03 +00:00
## Using a shortcode
2014-01-11 02:19:19 +00:00
2015-11-24 05:02:33 +00:00
In your content files, a shortcode can be called by using the `{{%/* name parameters
*/%}}` form. Shortcode parameters are space delimited. Parameters with spaces
can be quoted.
2014-01-11 02:19:19 +00:00
2014-02-18 23:35:03 +00:00
The first word is always the name of the shortcode. Parameters follow the name.
2015-11-24 05:02:33 +00:00
Depending upon how the shortcode is defined, the parameters may be named,
positional or both (although you can't mixed parameter types in a single call).
2014-10-07 23:52:58 +00:00
The format for named parameters models that of HTML with the format
2014-11-18 16:49:43 +00:00
`name="value"` .
2014-01-11 02:19:19 +00:00
2014-02-18 23:35:03 +00:00
Some shortcodes use or require closing shortcodes. Like HTML, the opening and closing
shortcodes match (name only), the closing being prepended with a slash.
Example of a paired shortcode:
2014-05-15 13:58:55 +00:00
2014-11-18 16:49:43 +00:00
{{< /* highlight go */>}} A bunch of code here {{</* /highlight */>}}
2014-02-18 23:35:03 +00:00
2014-11-18 16:49:43 +00:00
The examples above use two different delimiters, the difference being the `%` and the `<` character:
### Shortcodes with Markdown
The `%` characters indicates that the shortcode's inner content needs further processing by the page's rendering processor (i.e. Markdown), needed to get the **bold** text in the example below:
2015-11-24 05:02:33 +00:00
{{%/* myshortcode */%}}Hello * *World!**{{%/* /myshortcode */%}}
2014-11-18 16:49:43 +00:00
### Shortcodes without Markdown
The `<` character indicates that the shortcode's inner content doesn't need any further rendering, this will typically be pure HTML:
2015-11-24 05:02:33 +00:00
{{< /* myshortcode */>}}<p>Hello <strong>World!</strong></p>{{</* /myshortcode */>}}
2014-02-18 23:35:03 +00:00
2015-11-20 19:31:57 +00:00
## Built-in Shortcodes
2014-02-18 23:35:03 +00:00
Hugo ships with a set of predefined shortcodes.
2013-07-04 15:32:55 +00:00
2014-02-18 23:35:03 +00:00
### highlight
2013-07-04 15:32:55 +00:00
2014-02-18 23:35:03 +00:00
This shortcode will convert the source code provided into syntax highlighted
2015-01-28 02:17:09 +00:00
HTML. Read more on [highlighting ](/extras/highlighting/ ).
2014-01-11 02:19:19 +00:00
2014-02-18 23:35:03 +00:00
#### Usage
2015-11-24 05:02:33 +00:00
2014-10-07 23:52:58 +00:00
`highlight` takes exactly one required parameter of _language_ and requires a
2014-02-18 23:35:03 +00:00
closing shortcode.
2014-01-11 02:19:19 +00:00
2014-02-18 23:35:03 +00:00
#### Example
2014-05-15 13:58:55 +00:00
2014-11-18 16:49:43 +00:00
{{< /* highlight html */>}}
2014-02-18 23:35:03 +00:00
< section id = "main" >
< div >
< h1 id = "title" > {{ .Title }}< / h1 >
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
< / div >
< / section >
2014-11-18 16:49:43 +00:00
{{< /* /highlight */>}}
2014-02-18 23:35:03 +00:00
#### Example Output
< span style = "color: #f92672 " > < section</ span > < span style = "color: #a6e22e " > id=</ span >< span style = "color: #e6db74 " > " main" </ span >< span style = "color: #f92672 " > > </ span >
< span style = "color: #f92672 " > < div> </ span >
< span style = "color: #f92672 " > < h1</ span > < span style = "color: #a6e22e " > id=</ span >< span style = "color: #e6db74 " > " title" </ span >< span style = "color: #f92672 " > > </ span > {{ .Title }}< span style = "color: #f92672 " > < /h1> </ span >
{{ range .Data.Pages }}
{{ .Render " summary" }}
{{ end }}
< span style = "color: #f92672 " > < /div> </ span >
< span style = "color: #f92672 " > < /section> </ span >
2014-01-11 02:19:19 +00:00
2014-02-18 23:35:03 +00:00
### figure
2015-11-24 05:02:33 +00:00
2014-10-07 23:52:58 +00:00
`figure` is simply an extension of the image capabilities present with Markdown.
`figure` provides the ability to add captions, CSS classes, alt text, links etc.
2014-01-11 02:19:19 +00:00
2014-02-18 23:35:03 +00:00
#### Usage
2013-07-04 15:32:55 +00:00
2015-11-24 05:02:33 +00:00
`figure` can use the following named parameters:
2014-02-18 23:35:03 +00:00
* src
* link
* title
* caption
2015-02-07 05:21:56 +00:00
* class
2014-02-18 23:35:03 +00:00
* attr (attribution)
* attrlink
* alt
#### Example
2014-11-18 16:49:43 +00:00
{{< /* figure src="/media/spf13.jpg" title="Steve Francia" */>}}
2014-02-18 23:35:03 +00:00
#### Example output
2014-05-15 13:58:55 +00:00
< figure >
< img src = "/media/spf13.jpg" / >
< figcaption >
< h4 > Steve Francia< / h4 >
< / figcaption >
< / figure >
2014-02-18 23:35:03 +00:00
2014-11-25 08:07:18 +00:00
### ref, relref
These shortcodes will look up the pages by their relative path (e.g.,
`blog/post.md` ) or their logical name (`post.md`) and return the permalink
(`ref`) or relative permalink (`relref`) for the found page.
`ref` and `relref` also make it possible to make fragmentary links that work
for the header links generated by Hugo.
Read more on [cross-references ]({{% ref "extras/crossreferences.md" %}} ).
#### Usage
`ref` and `relref` take exactly one required parameter of _reference_ .
#### Example
[Neat ]({{</* ref "blog/neat.md" */>}} )
[Who ]({{</* relref "about.md#who" */>}} )
#### Example Output
Assuming that standard Hugo pretty URLs are turned on.
< a href = "/blog/neat" > Neat< / a >
< a href = "/about/#who:c28654c202e73453784cfd2c5ab356c0" > Who< / a >
2015-11-20 19:31:57 +00:00
### Twitter
2015-11-30 06:23:25 +00:00
You want to include a single tweet into your blog post? Everything you need is the URL of the tweet, e.g.:
2016-02-03 13:45:21 +00:00
2015-11-30 06:23:25 +00:00
* https://twitter.com/spf13/status/666616452582129664
2015-11-20 19:31:57 +00:00
2015-11-30 06:23:25 +00:00
Pass the tweet's ID from the URL as parameter to the shortcode as shown below:
2015-11-20 19:31:57 +00:00
2015-11-23 18:32:03 +00:00
{{< /* tweet 666616452582129664 */>}}
2015-11-20 19:31:57 +00:00
2015-11-30 06:23:25 +00:00
### YouTube
2015-11-20 19:31:57 +00:00
2015-11-30 06:23:25 +00:00
This shortcode embeds a responsive video player for [YouTube ](https://www.youtube.com/ ) videos. Only the ID of the video is required, e.g.:
2015-11-20 19:31:57 +00:00
2015-11-30 06:23:25 +00:00
* https://www.youtube.com/watch?v=w7Ft2ymGmfc
2015-11-20 19:31:57 +00:00
2016-02-13 15:41:25 +00:00
Copy the ID from behind `v=` and pass it to the shortcode:
2015-11-20 19:31:57 +00:00
2016-02-03 13:45:21 +00:00
{{< /* youtube w7Ft2ymGmfc */>}}
2015-11-20 19:31:57 +00:00
2016-01-16 17:49:18 +00:00
Furthermore, you can autostart the embedded video by setting the `autostart` parameter to true. Remember that you can't mix named an unamed parameters. Assign the yet unamed video id to the parameter `id` like below too.
{{< /* youtube id="w7Ft2ymGmfc" autoplay="true" */>}}
2015-11-20 19:31:57 +00:00
### Vimeo
2015-11-30 06:23:25 +00:00
Adding a video from [Vimeo ](https://vimeo.com/ ) is equivalent to the YouTube shortcode above. Extract the ID from the URL, e.g.:
2015-11-20 19:31:57 +00:00
2015-11-30 06:23:25 +00:00
* https://vimeo.com/channels/staffpicks/146022717
2015-11-20 19:31:57 +00:00
and pass it to the shortcode:
{{< /* vimeo 146022717 */>}}
2015-11-30 06:23:25 +00:00
### GitHub gists
2015-11-20 19:31:57 +00:00
2015-11-30 06:23:25 +00:00
Including code snippets with GitHub gists while writing a tutorial is common situation bloggers face. With a given URL of the gist, e.g.:
2015-11-20 19:31:57 +00:00
2015-11-30 06:23:25 +00:00
* https://gist.github.com/spf13/7896402
2015-11-20 19:31:57 +00:00
2015-11-30 06:23:25 +00:00
pass the owner and the ID of the gist to the shortcode:
2015-11-20 19:31:57 +00:00
2015-11-24 21:22:58 +00:00
{{< /* gist spf13 7896402 */>}}
2015-11-20 19:31:57 +00:00
2016-03-11 14:02:57 +00:00
If the gist contains several files and you want to quote just one of them, you can pass the filename (quoted) as an optional third argument:
{{< /* gist spf13 7896402 "img.html" */>}}
2015-11-30 06:23:25 +00:00
### Speaker Deck
2015-11-20 19:31:57 +00:00
2015-11-30 06:23:25 +00:00
To embed slides from [Speaker Deck ](https://speakerdeck.com/ ), click on "<  /> Embed" (under Share right next to the template on Speaker Deck) and copy the URL, e.g.:
2015-11-20 19:31:57 +00:00
< script async class = "speakerdeck-embed" data-id = "4e8126e72d853c0060001f97" data-ratio = "1.33333333333333" src = "//speakerdeck.com/assets/embed.js" > < / script >
2015-11-30 06:23:25 +00:00
Extract the value from the field `data-id` and pass it to the shortcode:
2015-11-20 19:31:57 +00:00
{{< /* speakerdeck 4e8126e72d853c0060001f97 */>}}
2016-11-13 23:04:28 +00:00
### Instagram
If you'd like to embed photo from [Instagram ](https://www.instagram.com/ ), all you need is photo ID from the URL, e. g.:
* https://www.instagram.com/p/BMokmydjG-M/
Pass it to the shortcode:
{{< /* instagram BMokmydjG-M */>}}
Optionally, hide caption:
{{< /* instagram BMokmydjG-M hidecaption */>}}
2015-11-20 19:31:57 +00:00
2014-02-18 23:35:03 +00:00
## Creating your own shortcodes
To create a shortcode, place a template in the layouts/shortcodes directory. The
template name will be the name of the shortcode.
2014-10-07 23:52:58 +00:00
In creating a shortcode, you can choose if the shortcode will use _positional
2015-11-30 06:23:25 +00:00
parameters_, or _named parameters_ , or _both_ . A good rule of thumb is that if a
2014-10-07 23:52:58 +00:00
shortcode has a single required value in the case of the `youtube` example below,
2014-02-18 23:35:03 +00:00
then positional works very well. For more complex layouts with optional
2015-11-24 05:02:33 +00:00
parameters, named parameters work best. Allowing both types of parameters is
useful for complex layouts where you want to set default values that can be
overridden.
2014-01-11 02:19:19 +00:00
**Inside the template**
2014-10-07 23:52:58 +00:00
To access a parameter by position, the `.Get` method can be used:
2014-01-11 02:19:19 +00:00
2014-02-26 04:57:31 +00:00
{{ .Get 0 }}
2014-01-11 02:19:19 +00:00
2014-10-07 23:52:58 +00:00
To access a parameter by name, the `.Get` method should be utilized:
2014-01-11 02:19:19 +00:00
2014-02-26 04:57:31 +00:00
{{ .Get "class" }}
2014-10-07 23:52:58 +00:00
`with` is great when the output depends on a parameter being set:
2014-02-26 04:57:31 +00:00
{{ with .Get "class"}} class="{{.}}"{{ end }}
2014-10-07 23:52:58 +00:00
`.Get` can also be used to check if a parameter has been provided. This is
2014-02-26 04:57:31 +00:00
most helpful when the condition depends on either one value or another...
2014-10-07 23:52:58 +00:00
or both:
2014-02-26 04:57:31 +00:00
{{ or .Get "title" | .Get "alt" | if }} alt="{{ with .Get "alt"}}{{.}}{{else}}{{.Get "title"}}{{end}}"{{ end }}
2014-01-11 02:19:19 +00:00
2014-10-01 07:51:25 +00:00
If a closing shortcode is used, the variable `.Inner` will be populated with all
2014-02-18 23:35:03 +00:00
of the content between the opening and closing shortcodes. If a closing
2014-10-01 07:51:25 +00:00
shortcode is required, you can check the length of `.Inner` and provide a warning
2014-02-18 23:35:03 +00:00
to the user.
2014-01-11 02:19:19 +00:00
2015-10-16 21:57:56 +00:00
A shortcode with `.Inner` content can be used without the inline content, and without the closing shortcode, by using the self-closing syntax:
2015-03-02 20:23:16 +00:00
{{< /* innershortcode /*/>}}
2015-11-24 05:02:33 +00:00
The variable `.Params` contains the list of parameters in case you need to do
more complicated things than `.Get` . It is sometimes useful to provide a
flexible shortcode that can take named or positional parameters. To meet this
need, Hugo shortcodes have a `.IsNamedParams` boolean available that can be used
such as `{{ if .IsNamedParams }}...{{ else }}...{{ end }}` . See the
`Single Flexible Example` below for an example.
2014-10-01 07:51:25 +00:00
2015-08-04 18:00:08 +00:00
You can also use the variable `.Page` to access all the normal [Page Variables ](/templates/variables/ ).
2014-10-01 07:51:25 +00:00
2016-03-08 19:56:24 +00:00
A shortcodes can be nested. In a nested shortcode you can access the parent shortcode context with `.Parent` . This can be very useful for inheritance of common shortcode parameters from the root.
2014-01-11 02:19:19 +00:00
## Single Positional Example: youtube
2014-11-18 16:49:43 +00:00
{{< /* youtube 09jf3ow9jfw */>}}
2013-07-04 15:32:55 +00:00
2013-12-11 00:36:44 +00:00
Would load the template /layouts/shortcodes/youtube.html
< div class = "embed video-player" >
< iframe class = "youtube-player" type = "text/html" width = "640" height = "385" src = "http://www.youtube.com/embed/{{ index .Params 0 }}" allowfullscreen frameborder = "0" >
< / iframe >
< / div >
2014-10-07 23:52:58 +00:00
This would be rendered as:
2013-07-04 15:32:55 +00:00
< div class = "embed video-player" >
< iframe class = "youtube-player" type = "text/html"
2014-10-07 23:52:58 +00:00
width="640" height="385"
2013-07-04 15:32:55 +00:00
src="http://www.youtube.com/embed/09jf3ow9jfw"
allowfullscreen frameborder="0">
< / iframe >
< / div >
2014-01-11 02:19:19 +00:00
## Single Named Example: image with caption
2013-07-04 15:32:55 +00:00
2014-11-18 16:49:43 +00:00
{{< /* img src="/media/spf13.jpg" title="Steve Francia" */>}}
2013-07-04 15:32:55 +00:00
2013-12-11 00:36:44 +00:00
Would load the template /layouts/shortcodes/img.html
2014-05-15 13:58:55 +00:00
2013-12-11 00:36:44 +00:00
<!-- image -->
2014-02-26 04:57:31 +00:00
< figure { { with . Get " class " } } class = "{{.}}" { { end } } >
{{ with .Get "link"}}< a href = "{{.}}" > {{ end }}
< img src = "{{ .Get " src " } } " { { if or ( . Get " alt " ) ( . Get " caption " ) } } alt = "{{ with .Get " alt " } } { { . } } { { else } } { { . Get " caption " } } { { end } } " { { end } } / >
{{ if .Get "link"}}< / a > {{ end }}
{{ if or (or (.Get "title") (.Get "caption")) (.Get "attr")}}
2013-12-11 00:36:44 +00:00
< figcaption > {{ if isset .Params "title" }}
2014-02-26 04:57:31 +00:00
< h4 > {{ .Get "title" }}< / h4 > {{ end }}
{{ if or (.Get "caption") (.Get "attr")}}< p >
{{ .Get "caption" }}
{{ with .Get "attrlink"}}< a href = "{{.}}" > {{ end }}
{{ .Get "attr" }}
{{ if .Get "attrlink"}}< / a > {{ end }}
2014-02-18 23:35:03 +00:00
< / p > {{ end }}
2013-12-11 00:36:44 +00:00
< / figcaption >
{{ end }}
< / figure >
<!-- image -->
2013-07-04 15:32:55 +00:00
Would be rendered as:
< figure >
< img src = "/media/spf13.jpg" / >
< figcaption >
< h4 > Steve Francia< / h4 >
< / figcaption >
< / figure >
2015-11-24 05:02:33 +00:00
## Single Flexible Example: vimeo with defaults
{{< /* vimeo 49718712 */>}}
{{< /* vimeo id="49718712" class="flex-video" */>}}
Would load the template /layouts/shortcodes/vimeo.html
{{ if .IsNamedParams }}
< div class = "{{ if .Get " class " } } { { . Get " class " } } { { else } } vimeo-container { { end } } " >
< iframe src = "//player.vimeo.com/video/{{ .Get " id " } } " allowfullscreen > < / iframe >
< / div >
{{ else }}
< div class = "{{ if len .Params | eq 2 }}{{ .Get 1 }}{{ else }}vimeo-container{{ end }}" >
< iframe src = "//player.vimeo.com/video/{{ .Get 0 }}" allowfullscreen > < / iframe >
< / div >
{{ end }}
Would be rendered as:
< div class = "vimeo-container" >
< iframe src = "//player.vimeo.com/video/49718712" allowfullscreen > < / iframe >
< / div >
< div class = "flex-video" >
< iframe src = "//player.vimeo.com/video/49718712" allowfullscreen > < / iframe >
< / div >
2014-01-11 02:19:19 +00:00
## Paired Example: Highlight
2014-10-07 23:52:58 +00:00
*Hugo already ships with the `highlight` shortcode*
2013-07-04 15:32:55 +00:00
2014-11-18 16:49:43 +00:00
{{< /* highlight html */>}}
2014-01-11 02:19:19 +00:00
< html >
< body > This HTML < / body >
< / html >
2014-11-18 16:49:43 +00:00
{{< /* /highlight */>}}
2013-07-04 15:32:55 +00:00
2015-11-30 06:23:25 +00:00
The template for this utilizes the following code (already included in Hugo)
2014-10-07 23:52:58 +00:00
2014-02-26 04:57:31 +00:00
{{ .Get 0 | highlight .Inner }}
2013-07-04 15:32:55 +00:00
2014-01-11 02:19:19 +00:00
And will be rendered as:
2013-07-04 15:32:55 +00:00
2014-01-11 02:19:19 +00:00
< div class = "highlight" style = "background: #272822 " >< pre style = "line-height: 125%" >< span style = "color: #f92672 " > < html> </ span >
< span style = "color: #f92672 " > < body> </ span > This HTML < span style = "color: #f92672 " > < /body> </ span >
< span style = "color: #f92672 " > < /html> </ span >
< / pre > < / div >
2013-07-04 15:32:55 +00:00
2014-10-07 23:52:58 +00:00
Please notice that this template makes use of a Hugo-specific template function
called `highlight` which uses Pygments to add the highlighting code.
2013-07-04 15:32:55 +00:00
2016-02-03 13:45:21 +00:00
## Simple Single-word Example: Year
Let's assume you would like to have a shortcode to be replaced by the current year in your Markdown content files, for a license or copyright statement. Calling a shortcode like this:
{{< /* year */>}}
... would load your one-line template ``/layouts/shortcodes/year.html``, which contains:
{{ .Page.Now.Year }}
2014-10-07 23:52:58 +00:00
More shortcode examples can be found at [spf13.com ](https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes ).