mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-30 04:03:30 -05:00
107 lines
4.1 KiB
Markdown
107 lines
4.1 KiB
Markdown
---
|
|
title: "Shortcodes"
|
|
date: "2013-07-01"
|
|
aliases: ["/doc/shortcodes/"]
|
|
groups: ["extras"]
|
|
groups_weight: 10
|
|
---
|
|
|
|
Because Hugo uses markdown for its content format, it was clear that there's a lot of things that
|
|
markdown doesn't support well. This is good, the simple nature of markdown is exactly why we chose it.
|
|
|
|
However we cannot 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 has full support for shortcodes.
|
|
|
|
### What is a shortcode?
|
|
A shortcode is a simple snippet inside a markdown file that Hugo will render using a template.
|
|
|
|
Short codes are designated by the opening and closing characters of '{{%' and '%}}' respectively.
|
|
Short codes are space delimited. The first word is always the name of the shortcode. Following the
|
|
name are the parameters. The author of the shortcode can choose if the short code
|
|
will use positional parameters or named parameters (but not both). A good rule of thumb is that if a
|
|
short code 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.
|
|
|
|
The format for named parameters models that of html with the format name="value"
|
|
|
|
### Example: youtube
|
|
*Example has an extra space so Hugo doesn't actually render it*
|
|
|
|
{{ % youtube 09jf3ow9jfw %}}
|
|
|
|
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>
|
|
|
|
This would be rendered as
|
|
|
|
<div class="embed video-player">
|
|
<iframe class="youtube-player" type="text/html"
|
|
width="640" height="385"
|
|
src="http://www.youtube.com/embed/09jf3ow9jfw"
|
|
allowfullscreen frameborder="0">
|
|
</iframe>
|
|
</div>
|
|
|
|
### Example: image with caption
|
|
*Example has an extra space so Hugo doesn't actually render it*
|
|
|
|
{{ % img src="/media/spf13.jpg" title="Steve Francia" %}}
|
|
|
|
Would load the template /layouts/shortcodes/img.html
|
|
|
|
<!-- image -->
|
|
<figure {{ if isset .Params "class" }}class="{{ index .Params "class" }}"{{ end }}>
|
|
{{ if isset .Params "link"}}<a href="{{ index .Params "link"}}">{{ end }}
|
|
<img src="{{ index .Params "src" }}" {{ if or (isset .Params "alt") (isset .Params "caption") }}alt="{{ if isset .Params "alt"}}{{ index .Params "alt"}}{{else}}{{ index .Params "caption" }}{{ end }}"{{ end }} />
|
|
{{ if isset .Params "link"}}</a>{{ end }}
|
|
{{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}}
|
|
<figcaption>{{ if isset .Params "title" }}
|
|
<h4>{{ index .Params "title" }}</h4>{{ end }}
|
|
{{ if or (isset .Params "caption") (isset .Params "attr")}}<p>
|
|
{{ index .Params "caption" }}
|
|
{{ if isset .Params "attrlink"}}<a href="{{ index .Params "attrlink"}}"> {{ end }}
|
|
{{ index .Params "attr" }}
|
|
{{ if isset .Params "attrlink"}}</a> {{ end }}
|
|
</p> {{ end }}
|
|
</figcaption>
|
|
{{ end }}
|
|
</figure>
|
|
<!-- image -->
|
|
|
|
Would be rendered as:
|
|
|
|
<figure >
|
|
<img src="/media/spf13.jpg" />
|
|
<figcaption>
|
|
<h4>Steve Francia</h4>
|
|
</figcaption>
|
|
</figure>
|
|
|
|
|
|
### Creating a shortcode
|
|
|
|
All that you need to do to create a shortcode is place a template in the layouts/shortcodes directory.
|
|
|
|
The template name will be the name of the shortcode.
|
|
|
|
**Inside the template**
|
|
|
|
To access a parameter by either position or name the index method can be used.
|
|
|
|
{{ index .Params 0 }}
|
|
or
|
|
{{ index .Params "class" }}
|
|
|
|
To check if a parameter has been provided use the isset method provided by Hugo.
|
|
|
|
{{ if isset .Params "class"}} class="{{ index .Params "class"}}" {{ end }}
|
|
|
|
|