--- aliases: - /doc/shortcodes/ date: 2013-07-01 menu: main: parent: extras next: /extras/pagination prev: /extras/permalinks title: Shortcodes weight: 80 toc: true --- Hugo uses Markdown for its simple content format. However, there are a lot of things that Markdown doesn’t support well. We are unwilling to accept being constrained by our simple format. Also unacceptable is writing raw HTML in our Markdown every time we want to include unsupported content such as a video. To do so is in complete opposition to the intent of using a bare bones format for our content and utilizing templates to apply styling for display. To avoid both of these limitations, Hugo created shortcodes. A 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 a functionality like that in a template, you most likely want a [partial template](/templates/partials/) instead. ## Using a shortcode In your content files, a shortcode can be called by using '`{{%/* name parameters */%}}`' respectively. Shortcodes are space delimited (parameters with spaces can be quoted). The first word is always the name of the shortcode. Parameters follow the name. The format for named parameters models that of HTML with the format `name="value"`. 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: {{}} A bunch of code here {{}} 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: ``` {{%/* myshortcode */%}}Hello **World!**{{%/* /myshortcode */%}} ``` ### Shortcodes without Markdown The `<` character indicates that the shortcode's inner content doesn't need any further rendering, this will typically be pure HTML: ``` {{}}

Hello World!

{{}} ``` ## Hugo Shortcodes Hugo ships with a set of predefined shortcodes. ### highlight This shortcode will convert the source code provided into syntax highlighted HTML. Read more on [highlighting](/extras/highlighting/). #### Usage `highlight` takes exactly one required parameter of _language_ and requires a closing shortcode. #### Example {{}}

{{}} #### Example Output <section id="main"> <div> <h1 id="title">{{ .Title }}</h1> {{ range .Data.Pages }} {{ .Render "summary"}} {{ end }} </div> </section> ### figure `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. #### Usage `figure` can use the following parameters: * src * link * title * caption * class * attr (attribution) * attrlink * alt #### Example {{}} #### Example output

### 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]({{}}) [Who]({{}}) #### Example Output Assuming that standard Hugo pretty URLs are turned on. Neat Who ## 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. In creating a shortcode, you can choose if the shortcode will use _positional parameters_ or _named parameters_ (but not both). A good rule of thumb is that if a shortcode has a single required value in the case of the `youtube` example below, then positional works very well. For more complex layouts with optional parameters, named parameters work best. **Inside the template** To access a parameter by position, the `.Get` method can be used: {{ .Get 0 }} To access a parameter by name, the `.Get` method should be utilized: {{ .Get "class" }} `with` is great when the output depends on a parameter being set: {{ with .Get "class"}} class="{{.}}"{{ end }} `.Get` can also be used to check if a parameter has been provided. This is most helpful when the condition depends on either one value or another... or both: {{ or .Get "title" | .Get "alt" | if }} alt="{{ with .Get "alt"}}{{.}}{{else}}{{.Get "title"}}{{end}}"{{ end }} If a closing shortcode is used, the variable `.Inner` will be populated with all of the content between the opening and closing shortcodes. If a closing shortcode is required, you can check the length of `.Inner` and provide a warning to the user. A shortcode with `.Inner` content can be used wihout the inline content, and without the closing shortcode, by using the self-closing syntax: {{}} The variable `.Params` contains the list of parameters in case you need to do more complicated things than `.Get`. You can also use the variable `.Page` to access all the normal [Page Variables](/templates/variables/). ## Single Positional Example: youtube {{}} Would load the template /layouts/shortcodes/youtube.html

This would be rendered as:

## Single Named Example: image with caption {{}} Would load the template /layouts/shortcodes/img.html

{{ if isset .Params "title" }}
{{ .Get "title" }}
{{ end }} {{ if or (.Get "caption") (.Get "attr")}}
{{ .Get "caption" }} {{ with .Get "attrlink"}} {{ end }} {{ .Get "attr" }} {{ if .Get "attrlink"}} {{ end }}
{{ end }}

Would be rendered as:

## Paired Example: Highlight *Hugo already ships with the `highlight` shortcode* {{}} This HTML {{}} The template for this utilizes the following code (already include in Hugo) {{ .Get 0 | highlight .Inner }} And will be rendered as:

<html>
        <body> This HTML </body>
    </html>

Please notice that this template makes use of a Hugo-specific template function called `highlight` which uses Pygments to add the highlighting code. More shortcode examples can be found at [spf13.com](https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes).

{{ .Title }}

Steve Francia

{{ .Get "title" }}

Steve Francia