1--- 2title: Shortcodes 3linktitle: 4description: Shortcodes are simple snippets inside your content files calling built-in or custom templates. 5date: 2017-02-01 6publishdate: 2017-02-01 7lastmod: 2019-11-07 8menu: 9 docs: 10 parent: "content-management" 11 weight: 35 12weight: 35 #rem 13categories: [content management] 14keywords: [markdown,content,shortcodes] 15draft: false 16aliases: [/extras/shortcodes/] 17testparam: "Hugo Rocks!" 18toc: true 19--- 20 21## What a Shortcode is 22 23Hugo loves Markdown because of its simple content format, but there are times when Markdown falls short. Often, content authors are forced to add raw HTML (e.g., video `<iframe>`'s) to Markdown content. We think this contradicts the beautiful simplicity of Markdown's syntax. 24 25Hugo created **shortcodes** to circumvent these limitations. 26 27A shortcode is a simple snippet inside a content file that Hugo will render using a predefined template. Note that shortcodes will not work in template files. If you need the type of drop-in functionality that shortcodes provide but in a template, you most likely want a [partial template][partials] instead. 28 29In addition to cleaner Markdown, shortcodes can be updated any time to reflect new classes, techniques, or standards. At the point of site generation, Hugo shortcodes will easily merge in your changes. You avoid a possibly complicated search and replace operation. 30 31## Use Shortcodes 32 33{{< youtube 2xkNJL4gJ9E >}} 34 35In your content files, a shortcode can be called by calling `{{%/* shortcodename parameters */%}}`. Shortcode parameters are space delimited, and parameters with internal spaces can be quoted. 36 37The first word in the shortcode declaration is always the name of the shortcode. Parameters follow the name. Depending upon how the shortcode is defined, the parameters may be named, positional, or both, although you can't mix parameter types in a single call. The format for named parameters models that of HTML with the format `name="value"`. 38 39Some shortcodes use or require closing shortcodes. Again like HTML, the opening and closing shortcodes match (name only) with the closing declaration, which is prepended with a slash. 40 41Here are two examples of paired shortcodes: 42 43``` 44{{%/* mdshortcode */%}}Stuff to `process` in the *center*.{{%/* /mdshortcode */%}} 45``` 46 47``` 48{{</* highlight go */>}} A bunch of code here {{</* /highlight */>}} 49``` 50 51The examples above use two different delimiters, the difference being the `%` character in the first and the `<>` characters in the second. 52 53### Shortcodes with raw string parameters 54 55{{< new-in "0.64.1" >}} 56 57You can pass multiple lines as parameters to a shortcode by using raw string literals: 58 59``` 60{{</* myshortcode `This is some <b>HTML</b>, 61and a new line with a "quoted string".` */>}} 62``` 63 64### Shortcodes with Markdown 65 66In Hugo `0.55` we changed how the `%` delimiter works. Shortcodes using the `%` as the outer-most delimiter will now be fully rendered when sent to the content renderer. They can be part of the generated table of contents, footnotes, etc. 67 68If you want the old behavior, you can put the following line in the start of your shortcode template: 69 70``` 71{{ $_hugo_config := `{ "version": 1 }` }} 72``` 73 74 75### Shortcodes Without Markdown 76 77The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without markdown include internal HTML: 78 79``` 80{{</* myshortcode */>}}<p>Hello <strong>World!</strong></p>{{</* /myshortcode */>}} 81``` 82 83### Nested Shortcodes 84 85You can call shortcodes within other shortcodes by creating your own templates that leverage the `.Parent` variable. `.Parent` allows you to check the context in which the shortcode is being called. See [Shortcode templates][sctemps]. 86 87## Use Hugo's Built-in Shortcodes 88 89Hugo ships with a set of predefined shortcodes that represent very common usage. These shortcodes are provided for author convenience and to keep your markdown content clean. 90 91### `figure` 92 93`figure` is an extension of the image syntax in markdown, which does not provide a shorthand for the more semantic [HTML5 `<figure>` element][figureelement]. 94 95The `figure` shortcode can use the following named parameters: 96 97src 98: URL of the image to be displayed. 99 100link 101: If the image needs to be hyperlinked, URL of the destination. 102 103target 104: Optional `target` attribute for the URL if `link` parameter is set. 105 106rel 107: Optional `rel` attribute for the URL if `link` parameter is set. 108 109alt 110: Alternate text for the image if the image cannot be displayed. 111 112title 113: Image title. 114 115caption 116: Image caption. Markdown within the value of `caption` will be rendered. 117 118class 119: `class` attribute of the HTML `figure` tag. 120 121height 122: `height` attribute of the image. 123 124width 125: `width` attribute of the image. 126 127attr 128: Image attribution text. Markdown within the value of `attr` will be rendered. 129 130attrlink 131: If the attribution text needs to be hyperlinked, URL of the destination. 132 133#### Example `figure` Input 134 135{{< code file="figure-input-example.md" >}} 136{{</* figure src="/media/spf13.jpg" title="Steve Francia" */>}} 137{{< /code >}} 138 139#### Example `figure` Output 140 141{{< output file="figure-output-example.html" >}} 142<figure> 143 <img src="/media/spf13.jpg" /> 144 <figcaption> 145 <h4>Steve Francia</h4> 146 </figcaption> 147</figure> 148{{< /output >}} 149 150### `gist` 151 152Bloggers often want to include GitHub gists when writing posts. Let's suppose we want to use the [gist at the following url][examplegist]: 153 154``` 155https://gist.github.com/spf13/7896402 156``` 157 158We can embed the gist in our content via username and gist ID pulled from the URL: 159 160``` 161{{</* gist spf13 7896402 */>}} 162``` 163 164#### Example `gist` Input 165 166If 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: 167 168{{< code file="gist-input.md" >}} 169{{</* gist spf13 7896402 "img.html" */>}} 170{{< /code >}} 171 172#### Example `gist` Output 173 174{{< output file="gist-output.html" >}} 175{{< gist spf13 7896402 >}} 176{{< /output >}} 177 178#### Example `gist` Display 179 180To demonstrate the remarkably efficiency of Hugo's shortcode feature, we have embedded the `spf13` `gist` example in this page. The following simulates the experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup. 181 182{{< gist spf13 7896402 >}} 183 184### `highlight` 185 186This shortcode will convert the source code provided into syntax-highlighted HTML. Read more on [highlighting](/tools/syntax-highlighting/). `highlight` takes exactly one required `language` parameter and requires a closing shortcode. 187 188#### Example `highlight` Input 189 190{{< code file="content/tutorials/learn-html.md" >}} 191{{</* highlight html */>}} 192<section id="main"> 193 <div> 194 <h1 id="title">{{ .Title }}</h1> 195 {{ range .Pages }} 196 {{ .Render "summary"}} 197 {{ end }} 198 </div> 199</section> 200{{</* /highlight */>}} 201{{< /code >}} 202 203#### Example `highlight` Output 204 205The `highlight` shortcode example above would produce the following HTML when the site is rendered: 206 207{{< output file="tutorials/learn-html/index.html" >}} 208<span style="color: #f92672"><section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">"main"</span><span style="color: #f92672">></span> 209 <span style="color: #f92672"><div></span> 210 <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> 211 {{ range .Pages }} 212 {{ .Render "summary"}} 213 {{ end }} 214 <span style="color: #f92672"></div></span> 215<span style="color: #f92672"></section></span> 216{{< /output >}} 217 218{{% note "More on Syntax Highlighting" %}} 219To see even more options for adding syntax-highlighted code blocks to your website, see [Syntax Highlighting in Developer Tools](/tools/syntax-highlighting/). 220{{% /note %}} 221 222### `instagram` 223 224If you'd like to embed a photo from [Instagram][], you only need the photo's ID. You can discern an Instagram photo ID from the URL: 225 226``` 227https://www.instagram.com/p/BWNjjyYFxVx/ 228``` 229 230#### Example `instagram` Input 231 232{{< code file="instagram-input.md" >}} 233{{</* instagram BWNjjyYFxVx */>}} 234{{< /code >}} 235 236You also have the option to hide the caption: 237 238{{< code file="instagram-input-hide-caption.md" >}} 239{{</* instagram BWNjjyYFxVx hidecaption */>}} 240{{< /code >}} 241 242#### Example `instagram` Output 243 244By adding the preceding `hidecaption` example, the following HTML will be added to your rendered website's markup: 245 246{{< output file="instagram-hide-caption-output.html" >}} 247{{< instagram BWNjjyYFxVx hidecaption >}} 248{{< /output >}} 249 250#### Example `instagram` Display 251 252Using the preceding `instagram` with `hidecaption` example above, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup. 253 254{{< instagram BWNjjyYFxVx hidecaption >}} 255 256 257 258{{% note %}} 259The `instagram`-shortcode refers an endpoint of Instagram's API, that's deprecated since October 24th, 2020. Thus, no images can be fetched from this API endpoint, resulting in an error when the `instagram`-shortcode is used. For more information please have a look at GitHub issue [#7879](https://github.com/gohugoio/hugo/issues/7879). 260{{% /note %}} 261 262### `param` 263 264Gets a value from the current `Page's` params set in front matter, with a fall back to the site param value. It will log an `ERROR` if the param with the given key could not be found in either. 265 266```bash 267{{</* param testparam */>}} 268``` 269 270Since `testparam` is a param defined in front matter of this page with the value `Hugo Rocks!`, the above will print: 271 272{{< param testparam >}} 273 274To access deeply nested params, use "dot syntax", e.g: 275 276```bash 277{{</* param "my.nested.param" */>}} 278``` 279 280### `ref` and `relref` 281 282These 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. 283 284`ref` and `relref` also make it possible to make fragmentary links that work for the header links generated by Hugo. 285 286{{% note "More on Cross References" %}} 287Read a more extensive description of `ref` and `relref` in the [cross references](/content-management/cross-references/) documentation. 288{{% /note %}} 289 290`ref` and `relref` take exactly one required parameter of _reference_, quoted and in position `0`. 291 292#### Example `ref` and `relref` Input 293 294``` 295[Neat]({{</* ref "blog/neat.md" */>}}) 296[Who]({{</* relref "about.md#who" */>}}) 297``` 298 299#### Example `ref` and `relref` Output 300 301Assuming that standard Hugo pretty URLs are turned on. 302 303``` 304<a href="https://example.com/blog/neat">Neat</a> 305<a href="/about/#who">Who</a> 306``` 307 308### `tweet` 309 310You want to include a single tweet into your blog post? Everything you need is the URL of the tweet: 311 312``` 313https://twitter.com/SanDiegoZoo/status/1453110110599868418 314``` 315 316#### Example `tweet` Input 317 318Pass the tweet's user (case-insensitive) and id from the URL as parameters to the `tweet` shortcode. 319 320{{< code file="example-tweet-input.md" >}} 321{{</* tweet user="SanDiegoZoo" id="1453110110599868418" */>}} 322{{< /code >}} 323 324#### Example `tweet` Output 325 326Using the preceding `tweet` example, the following HTML will be added to your rendered website's markup: 327 328{{< output file="example-tweet-output.html" >}} 329{{< tweet user="SanDiegoZoo" id="1453110110599868418" >}} 330{{< /output >}} 331 332#### Example `tweet` Display 333 334Using the preceding `tweet` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup. 335 336{{< tweet user="SanDiegoZoo" id="1453110110599868418" >}} 337 338### `vimeo` 339 340Adding a video from [Vimeo][] is equivalent to the [YouTube Input shortcode][]. 341 342``` 343https://vimeo.com/channels/staffpicks/146022717 344``` 345 346#### Example `vimeo` Input 347 348Extract the ID from the video's URL and pass it to the `vimeo` shortcode: 349 350{{< code file="example-vimeo-input.md" >}} 351{{</* vimeo 146022717 */>}} 352{{< /code >}} 353 354#### Example `vimeo` Output 355 356Using the preceding `vimeo` example, the following HTML will be added to your rendered website's markup: 357 358{{< output file="example-vimeo-output.html" >}} 359{{< vimeo 146022717 >}} 360{{< /output >}} 361 362{{% tip %}} 363If you want to further customize the visual styling of the YouTube or Vimeo output, add a `class` named parameter when calling the shortcode. The new `class` will be added to the `<div>` that wraps the `<iframe>` *and* will remove the inline styles. Note that you will need to call the `id` as a named parameter as well. You can also give the vimeo video a descriptive title with `title`. 364 365``` 366{{</* vimeo id="146022717" class="my-vimeo-wrapper-class" title="My vimeo video" */>}} 367``` 368{{% /tip %}} 369 370#### Example `vimeo` Display 371 372Using the preceding `vimeo` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup. 373 374{{< vimeo 146022717 >}} 375 376### `youtube` 377 378The `youtube` shortcode embeds a responsive video player for [YouTube videos][]. Only the ID of the video is required, e.g.: 379 380``` 381https://www.youtube.com/watch?v=w7Ft2ymGmfc 382``` 383 384 385#### Example `youtube` Input 386 387Copy the YouTube video ID that follows `v=` in the video's URL and pass it to the `youtube` shortcode: 388 389{{< code file="example-youtube-input.md" >}} 390{{</* youtube w7Ft2ymGmfc */>}} 391{{< /code >}} 392 393Furthermore, you can automatically start playback of the embedded video by setting the `autoplay` parameter to `true`. Remember that you can't mix named and unnamed parameters, so you'll need to assign the yet unnamed video id to the parameter `id`: 394 395 396{{< code file="example-youtube-input-with-autoplay.md" >}} 397{{</* youtube id="w7Ft2ymGmfc" autoplay="true" */>}} 398{{< /code >}} 399 400For [accessibility reasons](https://dequeuniversity.com/tips/provide-iframe-titles), it's best to provide a title for your YouTube video. You can do this using the shortcode by providing a `title` parameter. If no title is provided, a default of "YouTube Video" will be used. 401 402{{< code file="example-youtube-input-with-title.md" >}} 403{{</* youtube id="w7Ft2ymGmfc" title="A New Hugo Site in Under Two Minutes" */>}} 404{{< /code >}} 405 406 407#### Example `youtube` Output 408 409Using the preceding `youtube` example, the following HTML will be added to your rendered website's markup: 410 411{{< code file="example-youtube-output.html" >}} 412{{< youtube id="w7Ft2ymGmfc" autoplay="true" >}} 413{{< /code >}} 414 415#### Example `youtube` Display 416 417Using the preceding `youtube` example (without `autoplay="true"`), the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup. The video is also include in the [Quick Start of the Hugo documentation][quickstart]. 418 419{{< youtube w7Ft2ymGmfc >}} 420 421## Privacy Config 422 423To learn how to configure your Hugo site to meet the new EU privacy regulation, see [Hugo and the GDPR][]. 424 425## Create Custom Shortcodes 426 427To learn more about creating custom shortcodes, see the [shortcode template documentation][]. 428 429[`figure` shortcode]: #figure 430[contentmanagementsection]: /content-management/formats/ 431[examplegist]: https://gist.github.com/spf13/7896402 432[figureelement]: https://html5doctor.com/the-figure-figcaption-elements/ "An article from HTML5 doctor discussing the fig and figcaption elements." 433[Hugo and the GDPR]: /about/hugo-and-gdpr/ 434[Instagram]: https://www.instagram.com/ 435[pagevariables]: /variables/page/ 436[partials]: /templates/partials/ 437[quickstart]: /getting-started/quick-start/ 438[sctemps]: /templates/shortcode-templates/ 439[scvars]: /variables/shortcodes/ 440[shortcode template documentation]: /templates/shortcode-templates/ 441[templatessection]: /templates/ 442[Vimeo]: https://vimeo.com/ 443[YouTube Videos]: https://www.youtube.com/ 444[YouTube Input shortcode]: #youtube 445
