Hugo III: Shortcuts

Hugo Shortcodes are snippets or templates that can be used to extend basic markdown. They are called inside your markdown files to add HTML snippets to the final rendered HTML. Hugo comes with some built-in shortcodes, Docs, Content Management, Shortcodes.

Besides, they can be parameterized, that gives you additional flexibility and reusability.

• Styling Paragraphs

Let’s create a shortcode to styling paragraphs with your own CSS classes. Create a file in /layouts/shortcodes/pborder.html and add the following content:

{{ printf "<p class=\"bordes_redondeados\">"}}
	{{- .Inner | safeHTML -}}
{{ printf "</p>"}}

safeHTML declares the inner content passed to the shortcode as “safe” to avoid escaping by Go templates. You need to add some styling in your main.css:

	p.bordes_redondeados
	{
		-moz-border-radius:10px;
		-webkit-border-radius:10px;
		color: white;
		border-radius:10px;
		background-color: #00999F;
		outline:none;
		padding: 1em;
	}

Use (/content/myfolder/mypost.md):

	{{% pborder %}}
	This is how you style text with custom css class.
	{{% /pborder %}}

The end result is that it will render:

	<p class="bordes_redondeados">
	This is how you style text with custom css class.
	</p>

This is how you style text with custom css class.

• RAW HTML

If you want to add raw html to your markdown content, add a shortcode in layouts/shortcode/raw.html with the following content:

{{.Inner}}

It tells Hugo to render the content passed to the shortcode directly into HTML. Use:

{{< raw >}}
	2<sup>3</sup>
	<p class="my_custom_class">
		This is <strong>raw HTML</strong>.
	</p>
{{< /raw >}}

Inline Images. Let’s place an image in the text of a paragraph.

{{< raw >}} 
	<img src="../images/heart.png" style="width:10%;border:0;display:inline;margin:0 2px;box-shadow: none">
{{< /raw >}} respiration, 

… respiration,…

• Highlight some of your content in markdown

1. Create a shortcode: /layouts/shortcodes/highlight.html

   <mark>{{ with .Get 0 }}{{.}}{{end}}</mark>
   

2. Usage:

   This is some {{< highlight "highlighted text" >}}. Cool!
   

3. Style it:

   /* Styling the text that should be marked or highlighted*/
   mark {
   	background-color: yellow;
   	color: black;
   }
   

This is some highlighted text. Cool!

• Alert box

We can add support for bootstrap-style alert boxes by adding the following shortcode, alert.html

	<div class="alert alert-{{ .Get 0 }}">
		{{ .Inner | markdownify }}
	</div>

We are using .Get to gain access to our positional parameters passed to our shortcode. More specifically, we are retrieving the first parameter: {{ .Get 0 }} We are taking the .Inner variable that is populated with all the content between the opening and closing square bracket, and run it through the Markdown processor. As a result, we can format this content in Markdown as usual.

From now on, you can use it like this:

	{{< alert "primary">}}This is a **primary** alert.{{</alert >}}

• You could also include source code from an external file to your content. A. Let’s create a new shortcode /layouts/shortcode/render-code.html:

{{ $file := .Get "file" | readFile }} # It reads the file given as an argument.
{{ $lang := .Get "language" }} # It saves the source code's language in the $lang variable.
{{ (print "```" $lang "\n" $file "\n```") | markdownify }} 

Highlighting is carried out via the built-in highlight shortcode. Highlighting in code fences is enabled by default.

This is equivalent to:
	``` $lang
	$file - the content of the source code file given as an argument.
	```	

Finally, it pipes this content to markdonify, i.e., it runs this string through the Markdown processor.

B. Use:

    {{% render-code file="/static/uploads/antigravity.py" language="python" %}}

C. Credits: Much Ado About it, https://it.knightnet.org.uk/, Hugo Snippets and Code Examples

import antigravity

def main():
    antigravity.fly()

if __name__ == '__main__':
    main()

• Adding YouTube Videos and playlists.

  The YouTube shortcode embeds a responsive video player for YouTube videos. You only need to copy the YouTuve video ID, e.g., “ji5_MqicxSo”, https://www.youtube.com/watch?v=ji5_MqicxSo&ab_channel=CarnegieMellonUniversity (it follows v= in the video’s URL) and pass it to the YouTube shortcode:

  {{< youtube ji5_MqicxSo >}}
  

• How to embed a YouTube playlist? Create a /layouts/shortcodes/youtubepl.html (Credits: I’M YourOnly.One, stackflow)

    {{- $pc := .Page.Site.Config.Privacy.YouTube -}}
    {{- if not $pc.Disable -}}
    {{- $ytHost := cond $pc.PrivacyEnhanced  "www.youtube-nocookie.com" "www.youtube.com" -}}
    {{- $id := .Get "id" | default (.Get 0) -}}
    {{- $class := .Get "class" | default (.Get 1) -}}
    {{- $title := .Get "title" | default "YouTube Video" }}
    <div {{ with $class }}class="{{ . }}"{{ else }}style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;"{{ end }}>
      <iframe src="https://{{ $ytHost }}/embed/videoseries?list={{ $id }}{{ with .Get "autoplay" }}{{ if eq . "true" }}&autoplay=1{{ end }}{{ end }}" {{ if not $class }}style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border:0;" {{ end }}allowfullscreen title="{{ $title }}"></iframe>
    </div>
    {{ end -}}
  

  Usage: {{< youtubepl id="ID-HERE" >}}

• Using Webp Images.

  Let’s focus on the “Google’s WebP image format, and how you can take advantage of it to serve images that have all the visual fidelity your images have now, but at a fraction of the file size,” Using WEbP Images, CSS-Tricks, by Jeremy Wagner.

  We need to create a new shortcode, /layouts/shortcodes/img.html with the following code:

  <picture>
  {{ with .Get "link" }}<a href="{{ . }}">{{ end }}
      <source srcset="{{ .Get "src2" }}" />
      <img class="img-fluid" src="{{ .Get "src" }}" />
      {{ if .Get "link" }}</a>{{ end }}
      {{ if .Get "title" }}
      <figcaption>
        <h4>{{ .Get "title" }}</h4>
      </figcaption>
      {{ end }}
  </picture>
  

  We are using the .Get function to retrieve named parameters passed to our shortcode (src, src2, title, link). We also want it to be responsive and images in Bootstrap are made responsive with .img-fluid. Use:

  It will be rendered as an image using the HTML picture tag:

  <picture> 
    <a href="/code/">
      <source srcset="../images/mycomputerSEODigital.jpeg"  />
      <img class="img-fluid" src="../images/mycomputerSEODigital.jpeg"  />
    </a>
    <figcaption> 
      <h4>Programming in Hugo</h4>
    </figcaption>
  </picture>
  

  • Link to a file:

    1. Create a new shortcode /layouts/shortcode/staticref.html:
    <a href="{{ .Get 0 | relURL }}"{{ if len .Params | eq 2 }} target="_blank"{{ end }}>{{ .Inner }}</a>

    2. Use:
    {{% staticref "uploads/antigravity.py" "newtab" %}}Download antigravity.py{{% /staticref %}}

    3. Credits: https://wowchemy.com/, Learn, Docs, Create content, Page Elements.

Download antigravity.py

The core of this shortcode is: {{ .Get 0 | relURL }}. It reads the first argument and gets its URL. This is the link’s href attribute that specifies the URL of the page the link goes to.

If two arguments were provided {{ if len .Params | eq 2 }}, it opens the linked document in a new window or tab (target="_blank").