TheCloud/hugoDocs
1
0
Fork 0
mirror of https://github.com/gohugoio/hugoDocs.git synced 2025-09-18 19:04:40 -04:00
Code Issues Packages Projects Releases Wiki Activity

Add parent to shortcode docs

Browse Source 
Closes rdwatters/hugo-docs-concept#15
This commit is contained in:
Ryan Watters 2017-03-15 23:17:42 -05:00
parent e4c59bf042
commit fbc35a842e
2 changed files with 68 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
content/content-management/shortcodes.md
View File

@ -46,7 +46,7 @@ The examples above use two different delimiters, the difference being the `%` ch
### Shortcodes with Markdown
The `%` character indicates that the shortcode's inner content---called in the [shortcode template](/templates/shortcode-templates/) with the [`.Inner` variable](/variables/shortcodes/)---needs further processing by the page's rendering processor (i.e. Markdown via Blackfriday). In the following example, Blackfriday would convert `**World**` to `<strong>World</strong>`:
The `%` character indicates that the shortcode's inner content---called in the [shortcode template][sctemps] with the [`.Inner` variable][scvars]---needs further processing by the page's rendering processor (i.e. Markdown via Blackfriday). In the following example, Blackfriday would convert `**World**` to `<strong>World</strong>`:
```golang
{{%/* myshortcode */%}}Hello **World!**{{%/* /myshortcode */%}}
@ -60,6 +60,10 @@ The `<` character indicates that the shortcode's inner content does *not* need f
{{</* myshortcode */>}}<p>Hello <strong>World!</strong></p>{{</* /myshortcode */>}}
```
### Nested Shortcodes
You 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].
## Using Hugo's Built-in Shortcodes
Hugo 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.
@ -208,7 +212,7 @@ You also have the option to hide the caption:
By adding the preceding `hidecaption` example, the following HTML will be added to your rendered website's markup:
{{% output file="instagraph-hide-caption-output.html" %}}
{{% output file="instagram-hide-caption-output.html" %}}
```html
{{< instagram BMokmydjG-M hidecaption >}}
```
@ -397,16 +401,17 @@ Using the preceding `youtube` example (without `autoplay="true"`), the following
To learn more about creating your own shortcode templates, see the [shortcode template documentation][].
[`figure` shortcode]: #figure
[contentmanagementsection]: /content-management/formats/
[examplegist]: https://gist.github.com/spf13/7896402
[figureelement]: http://html5doctor.com/the-figure-figcaption-elements/ "An article from HTML5 doctor discussing the fig and figcaption elements."
[`figure` shortcode]: #figure
[Instagram]: https://www.instagram.com/
[pagevariables]: /variables/page/
[partials]: /templates/partials/
[Pygments]: http://pygments.org/
[quickstart]: /getting-started/quick-start/
[shortcode template documentation]: /templates/shortcode-templates/
[sctemps]: /templates/shortcode-templates/
[scvars]: /variables/shortcodes/
[Speaker Deck]: https://speakerdeck.com/
[templatessection]: /templates/
[Vimeo]: https://vimeo.com/

72
content/templates/shortcode-templates.md
View File

@ -1,5 +1,5 @@
---
title: Shortcode Templates
title: Creating Your Own Shortcode Templates
linktitle: Shortcode Templates
description: You can extend Hugo's built-in shortcodes by creating your own using the same templating syntax as that for single and list pages.
date: 2017-02-01
@ -117,9 +117,7 @@ Would load the template at `/layouts/shortcodes/youtube.html`:
```
{{% /code %}}
{{% output file="youtube-embed.html" %}}
{{% code file="youtube-embed.html" copy="false" %}}
```html
<div class="embed video-player">
<iframe class="youtube-player" type="text/html"
@ -129,7 +127,7 @@ Would load the template at `/layouts/shortcodes/youtube.html`:
</iframe>
</div>
```
{{% /output %}}
{{% /code %}}
### Single Named Example: `image`
@ -168,7 +166,7 @@ You have created the shortcode at `/layouts/shortcodes/img.html`, which loads th
Would be rendered as:
{{% output file="figure.html" %}}
{{% code file="img-output.html" copy="false" %}}
```html
<figure >
<img src="/media/spf13.jpg" />
@ -177,7 +175,7 @@ Would be rendered as:
</figcaption>
</figure>
```
{{% /output %}}
{{% /code %}}
### Single Flexible Example: `vimeo`
@ -204,7 +202,7 @@ Would load the template found at `/layouts/shortcodes/vimeo.html`:
Would be rendered as:
{{% output file="vimeo-iframes.html" %}}
{{% code file="vimeo-iframes.html" copy="false" %}}
```html
<div class="vimeo-container">
<iframe src="//player.vimeo.com/video/49718712" allowfullscreen></iframe>
@ -213,7 +211,7 @@ Would be rendered as:
<iframe src="//player.vimeo.com/video/49718712" allowfullscreen></iframe>
</div>
```
{{% /output %}}
{{% /code %}}
### Paired Example: `highlight`
@ -237,22 +235,69 @@ The template for the `highlight` shortcode uses the following code, which is alr
The rendered output of the HTML example code block will be as follows:
{{% output file="syntax-highlighted.html" %}}
{{% code file="syntax-highlighted.html" copy="false" %}}
```html
<div class="highlight" style="background: #272822"><pre style="line-height: 125%"><span style="color: #f92672">&lt;html&gt;</span>
<span style="color: #f92672">&lt;body&gt;</span> This HTML <span style="color: #f92672">&lt;/body&gt;</span>
<span style="color: #f92672">&lt;/html&gt;</span>
</pre></div>
```
{{% /output %}}
{{% /code %}}
{{% note %}}
The preceding shortcode makes use of a Hugo-specific template function called `highlight`, which uses [Pygments](http://pygments.org) to add syntax highlighting to the example HTML code block. See the [developer tools page on syntax highlighting](/tools/syntax-highlighting/) for more information.
{{% /note %}}
### Nested Shortcode: Image Gallery
Hugo's [`.Parent` shortcode variable][parent] returns a boolean value depending on whether the shortcode in question is called within the context of a *parent* shortcode. This provides an inheritance model for common shortcode parameters.
The following example is contrived but demonstrates the concept. Assume you have a `gallery` shortcode that expects one named `class` parameter:
{{% code file="layouts/shortcodes/gallery.html" %}}
```html
<div class="{{.Get "class"}}">
{{.Inner}}
</div>
```
{{% /code %}}
You also have an `image` shortcode with a single named `src` parameter that may or may not be called within `gallery`, as well as other shortcodes you've created for your site. When called inside a parent shortcode like `gallery`, you want the output HTML to inherit a CSS class from the value given to its parent:
{{% code file="layouts/shortcodes/image.html" %}}
```html
{{- $src := .Get "src" -}}
{{- with .Parent -}}
<img src="{{$src}}" class="{{.Get "class"}}-image">
{{- else -}}
<img src="{{$src}}">
{{- end }}
```
{{% /code %}}
You can then call your shortcode in your content as follows:
```markdown
{{</* gallery class="content-gallery" */>}}
{{</* img src="/images/one.jpg" */>}}
{{</* img src="/images/two.jpg" */>}}
{{</* /gallery */>}}
{{</* img src="/images/three.jpg" */>}}
```
This will output the following HTML. Note how the first two `image` shortcodes inherit the `class` value of `content-gallery` set with the call to the parent `gallery`, whereas the third `image` only uses `src`:
```html
<div class="content-gallery">
<img src="/images/one.jpg" class="content-gallery-image">
<img src="/images/two.jpg" class="content-gallery-image">
</div>
<img src="/images/three.jpg">
```
## More Shortcode Examples
More shortcode examples can be found in the [shortcodes directory for spf13.com][spf13shortcodes] and the [shortcodes directory for the Hugo docs][docsshortcodes].
More shortcode examples can be found in the [shortcodes directory for spf13.com][spfscs] and the [shortcodes directory for the Hugo docs][docsshortcodes].
[basic content files]: /content-management/formats/ "See how Hugo leverages markdown--and other supported formats--to create content for your website."
[built-in shortcode]: /content-management/shortcodes/
@ -260,8 +305,9 @@ More shortcode examples can be found in the [shortcodes directory for spf13.com]
[docsshortcodes]: https://github.com/spf13/hugo/tree/master/docs/layouts/shortcodes "See the shortcode source directory for the documentation site you're currently reading."
[figure]: /content-management/shortcodes/#figure
[pagevars]: /variables/page/ "See which variables you can leverage in your templating for page vs list templates."
[parent]: /variables/shortcodes/
[shortcodesvars]: /variables/shortcodes/ "Certain variables are specific to shortcodes, although most .Page variables can be accessed within your shortcode template."
[spf13shortcodes]: https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes "See more examples of shortcodes by visiting the shortcode directory of the source for spf13.com, the blog of Hugo's creator, Steve Francia."
[spfscs]: https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes "See more examples of shortcodes by visiting the shortcode directory of the source for spf13.com, the blog of Hugo's creator, Steve Francia."
[templates]: /templates/ "The templates section of the Hugo docs."
[vimeoexample]: #single-flexible-example-vimeo
[youtubeshortcode]: /content-management/shortcodes/#youtube "See how to use Hugo's built-in YouTube shortcode."