55fcd2f30f
This commit contains a restructuring and partial rewrite of the shortcode handling.
Prior to this commit rendering of the page content was mingled with handling of the shortcodes. This led to several oddities.
The new flow is:
1. Shortcodes are extracted from page and replaced with placeholders.
2. Shortcodes are processed and rendered
3. Page is processed
4. The placeholders are replaced with the rendered shortcodes
The handling of summaries is also made simpler by this.
This commit also introduces some other chenges:
1. distinction between shortcodes that need further processing and those who do not:
* `{{< >}}`: Typically raw HTML. Will not be processed.
* `{{% %}}`: Will be processed by the page's markup engine (Markdown or (infuture) Asciidoctor)
The above also involves a new shortcode-parser, with lexical scanning inspired by Rob Pike's talk called "Lexical Scanning in Go",
which should be easier to understand, give better error messages and perform better.
2. If you want to exclude a shortcode from being processed (for documentation etc.), the inner part of the shorcode must be commented out, i.e. `{{%/* movie 47238zzb */%}}`. See the updated shortcode section in the documentation for further examples.
The new parser supports nested shortcodes. This isn't new, but has two related design choices worth mentioning:
* The shortcodes will be rendered individually, so If both `{{< >}}` and `{{% %}}` are used in the nested hierarchy, one will be passed through the page's markdown processor, the other not.
* To avoid potential costly overhead of always looking far ahead for a possible closing tag, this implementation looks at the template itself, and is branded as a container with inner content if it contains a reference to `.Inner`
Fixes #565
Fixes #480
Fixes #461
And probably some others.
7.9 KiB
| aliases | date | menu | next | prev | title | weight | |||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
2013-07-01 |
|
/extras/highlighting | /extras/permalinks | Shortcodes | 40 |
Hugo uses Markdown for its simple content format. However, there’s 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 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". The current implementation only supports this exact format. Extra
spaces or different quotation marks will not parse properly.
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:
{{%/* highlight go */%}} A bunch of code here {{%/* /highlight */%}}
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.
Usage
highlight takes exactly one required parameter of language and requires a
closing shortcode.
Example
{{%/* highlight html */%}}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
{{%/* /highlight */%}}
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>
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
- attr (attribution)
- attrlink
- alt
Example
Example has an extra space so Hugo doesn’t actually render it.
{{%/* figure src="/media/spf13.jpg" title="Steve Francia" */%}}
Example output
<figure>
<img src="/media/spf13.jpg" />
<figcaption>
<h4>Steve Francia</h4>
</figcaption>
</figure>
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.
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.
Single Positional Example: youtube
{{%/* 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>
Single Named 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 {{ 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")}}
<figcaption>{{ if isset .Params "title" }}
<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 }}
</p> {{ end }}
</figcaption>
{{ end }}
</figure>
<!-- image -->
Would be rendered as:
<figure >
<img src="/media/spf13.jpg" />
<figcaption>
<h4>Steve Francia</h4>
</figcaption>
</figure>
Paired Example: Highlight
Hugo already ships with the highlight shortcode
Example has an extra space so Hugo doesn’t actually render it.
{{%/* highlight html */%}}
<html>
<body> This HTML </body>
</html>
{{%/* /highlight */%}}
The template for this utilizes the following code (already include in Hugo)
{{ .Get 0 | highlight .Inner }}
And will be rendered as:
<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>
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.