Shortcodes

Ox-hugo will not officially support verbatim use of Hugo shortcodes in Org source, like you would do in Hugo Markdown source. But here are few ways how you can either mimic them or include them indirectly.

1 Org Special Blocks #

With a little bit of CSS and Org Special Blocks , we can mimic some of the Hugo Shortcodes in Org itself.

Here is some CSS inspired from the Docsy theme’s alert shortcode:

.alert {
  position: relative;
  padding: 0rem 1rem;
  margin-bottom: 1rem;
  border: 1px solid transparent;
}

.alert-warning {
  border-style: solid;
  border-color: #ed6a5a;
  border-width: 0 0 0 4px;
}

.alert-heading {
  font-family: sans-serif;
  font-size: 1.5rem;
  color: #ed6a5a;
  weight: bold;
}

With that CSS, and the below Org snippet:

#+attr_html: :class alert-warning
#+begin_alert
#+begin_alert-heading
Warning
#+end_alert-heading
This is a warning.
#+end_alert

we get this:

2 HUGO_PAIRED_SHORTCODES #

The Org Special Blocks export paired Hugo Shortcodes for a special block tag that’s added to the HUGO_PAIRED_SHORTCODES keyword.

2.1 Non-Markdown Shortcodes ({{< .. >}}) #

The content within these shortcodes is not parsed by the Hugo Markdown parser. See Hugo Doc – Shortcodes Without Markdown.

1. Use :EXPORT_HUGO_PAIRED_SHORTCODES: myshortcode property or #+hugo_paired_shortcodes: myshortcode keyword to let the Org Special Block parsing logic know that “myshortcode” tag needs to be exported as a paired shortcode.
2. Use the Org Special Block:

   #+begin_myshortcode
   Something
   #+end_myshortcode
   

Above will export as:

{{< myshortcode >}}
Something
{{< /myshortcode >}}

2.1.1 Shortcodes with positional arguments #

If the Hugo shortcode accepts positional arguments, they need to be specified using the #+attr_shortcode keyword.

For example,

#+attr_shortcode: argval1 "arg val 2"
#+begin_myshortcode
Something
#+end_myshortcode

will export as:

{{< myshortcode argval1 "arg val 2" >}}
Something
{{< /myshortcode >}}

2.1.2 Shortcodes with named arguments #

#+attr_shortcode keyword can be used to also specify a shortcode’s named arguments.

For example,

#+attr_shortcode: :arg1 foo bar :arg2 color: red; text-align: center;
#+begin_myshortcode
Something
#+end_myshortcode

will export as:

{{< myshortcode arg1="foo bar" arg2="color: red; text-align: center;" >}}
Something
{{< /myshortcode >}}

2.2 Markdown Shortcodes ({{% .. %}}) #

The content within these shortcodes is parsed by the Hugo Markdown parser. See Hugo Doc – Shortcodes With Markdown.

Only the syntax for specifying these shortcodes is different — You need to prefix the shortcode with %.

Example: :EXPORT_HUGO_PAIRED_SHORTCODES: %myshortcode in the post subtree’s property drawer or #+hugo_paired_shortcodes: %myshortcode as a keyword.

2.3 alert2 shortcode example #

An alert2 shortcode definition is saved to this site’s layouts/shortcodes/alert2.html which looks like this:

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

:EXPORT_HUGO_PAIRED_SHORTCODES: alert2 is added to this post’s subtree in Org source so that the Org Special Block parser knows to treat that tag differently (i.e. export as a non-Markdown Hugo shortcode).

With that, this Org snippet:

#+attr_shortcode: warning
#+begin_alert2
This is a warning.
#+end_alert2

exports as:

{{< alert2 warning >}}
This is a warning.
{{< /alert2 >}}

and renders as this:

You might notice that the same Alert CSS from the previous section is applied here too.

3 Quoting Hugo-specific exports #

The Org source should contain only Org syntax text which could be parsed in general by any of the built-in Org exporters.

So ox-hugo does not recommend or support using raw Hugo shortcodes directly in Org source as shown below:

# Bad !!
{{< alert2 warning >}}
This is a warning.
{{< /alert2 >}}

But many times, one might also want to use one of the unpaired Hugo shortcodes like relref. These too, you cannot directly inline them but you can use one of these methods.

3.1 @@hugo:..@@ #

This links to the @@hugo:[Org Special Blocks]({​{< relref "org-special-blocks" >}})@@ page.

Above renders to:

This links to the Org Special Blocks page.

See Org Info: Quoting HTML tags for reference.

Using @@md:..@@ or @@html:..@@ will also export the same way.

3.2 #+hugo: Keyword #

Sometimes, it might also be possible to export the whole line in the specified backend like so:

#+hugo: This links to the [Org Special Blocks]({​{< relref "org-special-blocks" >}}) page.

Above renders to:

This links to the Org Special Blocks page.

Using #+md:.. or #+html:.. will also export the same way.

3.3 #+begin_export hugo #

The earlier sections Org Special Blocks and Hugo Paired Shortcodes are the recommended methods if you really want to blend Hugo shortcodes with your Org source.

Even though discouraged, this method is documented for the sake of completeness.

#+begin_export hugo
{{< alert2 warning >}}
This is a warning.
{{< /alert2 >}}
#+end_export

renders as:

3.3.1 Multi-line shortcodes #

Hugo supports unpaired shortcodes written over multiple lines.

For example, if you have an unpaired shortcode called album which accepts multiple arguments, you can write it like below (but it’s discouraged) for readability.

#+begin_export hugo
{{< album
    position="horizontal"
    path="static/img/some/very/long/path"
>}}
#+end_export

4 Org Macros #

If you find yourself using the @@hugo:..@@ Inline Syntax a lot, you might appreciate the power of Org Macros.

This is best shown using the same relref shortcode example ..

Instead of always typing @@hugo:[Org Special Blocks]({​{< relref "org-special-blocks" >}})@@, you can define an Org macro called relref like so:

#+macro: relref @@hugo:[@@ $1 @@hugo:]({{< relref "$2" >}})@@

And then,

This links to the {{{relref(Org Special Blocks,org-special-blocks)}}} page.

will also render to:

This links to the Org Special Blocks page.