diff --git a/content/content-management/shortcodes.md b/content/content-management/shortcodes.md index 2c46e6af2..af398bc21 100644 --- a/content/content-management/shortcodes.md +++ b/content/content-management/shortcodes.md @@ -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 `World`: +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 `World`: ```golang {{%/* myshortcode */%}}Hello **World!**{{%/* /myshortcode */%}} @@ -60,6 +60,10 @@ The `<` character indicates that the shortcode's inner content does *not* need f {{}}

Hello World!

{{}} ``` +### 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/ diff --git a/content/templates/shortcode-templates.md b/content/templates/shortcode-templates.md index 83b8e3c4a..72e08a023 100644 --- a/content/templates/shortcode-templates.md +++ b/content/templates/shortcode-templates.md @@ -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
@@ -213,7 +211,7 @@ Would be rendered as:
``` -{{% /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 
<html>
     <body> This HTML </body>
 </html>
``` -{{% /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 +
+ {{.Inner}} +
+``` +{{% /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 -}} + +{{- else -}} + +{{- end }} +``` +{{% /code %}} + +You can then call your shortcode in your content as follows: + +```markdown +{{}} + {{}} + {{}} +{{}} +{{}} +``` + +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 +
+ + +
+ +``` + ## 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." \ No newline at end of file