Hugo shortcodes are simple snippets inside your content files calling built-in or custom templates, as described in the relevant Hugo documentation page. As a newcomer in the Hugo-space, and having red the documentation, I wanted a few simple examples for custom shortcodes, as a proof-of-concept to get me started. Following are a couple such example-snippets for the newcomers.

Custom html injection

Scenario: Sometimes markdown syntax is not enough for your formating needs, or you want to insert content that can be reusable. Specifically, you would like to add a section below main content, in the markdown file (.md), for licensing-related material, that can be reused in other articles.

1. Create the custom shortcode template file.

   First you have to create a template file for the shortcode in your project’s directory structure. Under directory layouts create a new directory shortcodes. In the directory shortcodes create a new .html file. Usually you would like to give this file a name relevant to the shortcode’s scope, as this name will be used to “call” the shortcode in your markdown file. Let’s call the new file footerclaim.html, for this example.

2. Add the contents of the template file.

   Append the template file according to your needs. You can combine html syntax and Go html/template syntax. For this example you could use the following:

   <div class="footerclaim">The code samples provided are licensed under the
   <a href="https://www.apache.org/licenses/LICENSE-2.0" target="_blank">Apache
   2.0 License</a> and rest content of this page is licensed under the
   <a href="https://creativecommons.org/licenses/by/3.0/" target="_blank">
   Creative Commons Attribution 3.0 License</a>, except if noted otherwise.
   </div>
   

3. Style the <div>.

   Create a style for class .footerclaim in your stylesheet (or inline), according to your preferences, or use something like:

   .footerclaim {
       border-top: 1px solid #cecece;
       padding-top: 1em;
       margin-top: 20px;
       font-size: 0.875em;
       font-style: italic;
       line-height: 1.5;
   }
   

4. Add the shortcode to your markdown file.

   Finally, use the custom shortcode footerclaim in your markdown file. This is done by adding {{< footerclaim >}} where you believe is an appropriate place within your content. As an example in the file nice_content.md the shortcode could be used like so:

   ...Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
   incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
   exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
   
   Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
   fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
   culpa qui officia deserunt mollit anim id est laborum.
   
   {{< footerclaim >}}
   

5. Observe the result.

   If your Hugo server is not already running, you can start Hugo server, while in the root directory of your project, by typing at the command line:

    $ hugo server -D
   

   You should be able now to observe the executed shortcode, at the end of your content, as rendered in html by Hugo. The result should be similar to the footnote after the end of this article.

Custom html injection with input text

Scenario: A predefined text is not enough in some use cases. Maybe, you would like to have reusable custom html with variable text depending on the context or scope of your content. Specifically, you would like to add a section above the main content, in the markdown file (.md), with information about the material that follows, that can also be reused in other articles.

1. Create the custom shortcode template file.

   Like in the previous example, first you have to create a template file for the shortcode in your project’s directory structure. Under directory layouts create a new directory shortcodes (if there is not one already there). In the directory shortcodes create a new .html file. As usual, you would like to give this file, a name relevant to the shortcode’s scope, as this name will be used to “call” the shortcode in your markdown file. Let’s call the new file headerclaim.html, for this example.

2. Add the contents of the template file.

   Append the template file according to your needs. You can combine html syntax and Go html/template syntax. For this example you could use the following:

   <div class="headerclaim">{{.Get "claimtext" }}
   </div>
   

3. Style the <div>.

   Create a style for class .headerclaim in your stylesheet (or inline), according to your preferences, or use something like:

   .headerclaim {
       font-size: 0.875em;
       font-style: italic;
       line-height: 1.5;
   }
   

4. Add the shortcode to your markdown file.

   Finally, use the custom shortcode headerclaim in your markdown file. This is done by adding {{< headerclaim >}} where you believe is an appropriate place within your content. As an example in the file nice_content.md the shortcode could be used like so (remove the {{< footerclaim >}}, if you have not followed the previous example):

   {{< headerclaim claimtext="(Examples of Hugo shortcodes following.)" >}}
   
   ...Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
   incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
   exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
   
   Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
   fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
   culpa qui officia deserunt mollit anim id est laborum.
   
   {{< footerclaim >}}
   

5. Observe the result.

   If your Hugo server is not already running, you can start Hugo server, while in the root directory of your project, by typing at the command line:

    $ hugo server -D
   

   You should be able now to observe the executed shortcode, at the top of your content, as rendered in html by Hugo. The result should be similar to the starting notice (The following assume Linux OS, Hugo…) at the top of this article.

Custom html injection with .Inner

Scenario: Custom html with variable plain text is not enough. Maybe, you would like to insert a link reference in the text. For this example you can modify the shortcode template file created in the previous example.

1. Open the custom shortcode template file headerclaim.html, you created in the previous example.

2. Change the contents of the template file and save the file.

   For this example, append the shortcode file as follows (for Hugo versions before v0.55):

   <div class="headerclaim">{{- .Inner -}}</div>
   

   For Hugo v0.55 and later versions, since the behavior of shortcodes using the {{% %}} delimiters changed, you should instead append your template:

   {{ $_hugo_config := `{ "version": 1 }` }}
   <div class="headerclaim">{{- .Inner -}}</div>
   

   This will instruct the renderer to use the old behavior, or to achieve the same result with the new behavior you could use:

   <div class="headerclaim">{{- .Inner | markdownify -}}</div>
   

   In v0.60 the default library used for Markdown in Hugo was changed to Goldmark. This means that with default options the above methods will not be rendered unless you enable unsafe mode:

   [markup.goldmark.renderer]
   unsafe= true
   

   To use the new .RenderString function introduced in release v0.62 you could change your shortcode template to:

   <div class="headerclaim">{{- .Inner | .Page.RenderString -}}</div>
   

3. I assume you have already styled the <div> from the previous example. If not you can apply the same styling as before.

4. Add the shortcode to your markdown file.

   Finally, use the appended custom shortcode headerclaim in your markdown file. The shortcode as it is defined now can be used with a closing shortcode which is done by adding {{< /headerclaim >}} at the end of the shortcode content. As an example in the file nice_content.md the shortcode could be used like so:

   {{% headerclaim %}}(Examples of [Hugo](https://gohugo.io/) shortcodes following.){{% /headerclaim %}}
   
   ...Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
   incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
   exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
   
   Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
   fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
   culpa qui officia deserunt mollit anim id est laborum.
   

   The above example uses % instead of <, > because the shortcode’s inner content needs further processing (to process the external link) by the page’s rendering processor.

   NOTE: If you want to use .RenderString function, available from release v0.62 you should replace % with < and > in your markdown file:

   {{< headerclaim >}}(Examples of [Hugo](https://gohugo.io/) shortcodes following.){{< /headerclaim >}}
   
   ...Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
   incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
   exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
   
   Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
   fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
   culpa qui officia deserunt mollit anim id est laborum.
   

5. Observe the result.

   If your Hugo server is not already running, you can start Hugo server, while in the root directory of your project, by typing at the command line:

    $ hugo server -D
   

   You should be able now, to observe the executed shortcode, at the top of your content, as rendered in html by Hugo. The result should be similar to:

   <div class="renderedhtml">
   <span>(Examples of <a href="https://gohugo.io/" target="_blank">Hugo</a> shortcodes following.)</span>
   
   <span>...Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
   incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
   exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</span>
   
   <span>Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
   fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
   culpa qui officia deserunt mollit anim id est laborum.</span>
   </div>
   

Enjoy coding!

References for further reading:

1. Hugo shortcodes