Hugo’s .RenderString Method
(featuring AsciiDoc admonitions in Markdown)
Updated  by  nm  2024-February-22

Page contents

News

2023-August-1  As of today, this evolving⁠[1] article has been on the web for 2 years.🕯🕯

 

Prerequisites

This article assumes you know the basics about the Hugo static site generator.

 

Hugo has markdownify but not asciidocify

Since 2015, Hugo has had a function called markdownify that converts Markdown markup to HTML. I’ve often wished Hugo had a function or method — let’s call it asciidocify — that would convert AsciiDoc markup to HTML.

 

The .RenderString method to the rescue

Starting with Hugo v0.62.0, which was released in late 2019, there is a method called .RenderString that converts any markup language Hugo supports (AsciiDoc, Markdown, Org-⁠mode, etc.) to HTML. This means you can write your layout files in Go HTML⁠[2] along with any markup language Hugo supports.

In a nutshell, the syntax is this:

.RenderString [OPTIONS] MARKUP

Or, in a pipeline, this:

MARKUP | .RenderString [OPTIONS]

 

To learn more about the .RenderString method and its optional dictionary (dict)⁠[3] argument, see…

 

.RenderString example

Thanks to the .RenderString method, I can use AsciiDoc in Hugo layout files. For example, here is an excerpt of one of Infinite Ink’s layout files:

{{ if .Params.mathjax }}
<noscript>

{{ "NOTE: To render the link:/portal/mathjax/[MathJax] markup on this page, enable JavaScript in your web browser." | .RenderString (dict "markup" "adoc" "display" "block") }}

</noscript>
{{ end }}

 

When Hugo, with help from the Asciidoctor Ruby gem, generates the Infinite Ink website, the above layout fragment produces the following AsciiDoc admonition.⁠[4]

 

ℹ
To render the MathJax markup on this page, enable JavaScript in your web browser.

 

To learn how this Infinite Ink website uses this Go HTML layout fragment, see AsciiDoc Passthroughs, Hugo, LaTeX, and MathJax on Infinite Ink.

 

Infinite Ink’s renderas shortcode

To use .RenderString in a file in the content/ directory, rather than a file in the layouts/ directory, you need to use a Hugo shortcode.

 

The shortcode

I created the following shortcode called renderas that can be called with one of Hugo’s markup language identifiers (ad, adoc, asciidocext, goldmark, htm, html, markdown, md, mdown, org, pandoc, pdc, or rst).

 

layouts/shortcodes/renderas.html
{{/*
CREATED: 2021-July by nm

PATH: layouts/shortcodes/renderas.html

EXAMPLE USAGE:

{{< renderas adoc >}}
AsciiDoc markup
{{< /renderas >}}

*/}}

{{ $options := (dict
  "markup" (.Get 0)
  "display" "block"
) }}

{{ .Inner | .Page.RenderString $options }}

Note that in Hugo templates, a statement (such as {{ $options := … }} used above) can be split over multiple lines. This is discussed in gohugo.io’s Introduction to Hugo Templating.

 

Shortcode example 1: Use an AsciiDoc admonition in a Markdown content file

This renderas shortcode is used in Infinite Ink’s Ordinary and Extraordinary Markdown, which is written in Markdown, like this:

content/ordinary-extraordinary-markdown.md excerpt
{{< renderas adoc >}}

[TIP]
====
If _you_ control your
Hugo content files, it's safe to specify
`unsafe:&nbsp;true` in your Hugo config file.
====

{{< /renderas >}}

 

After Hugo generates the Infinite Ink website, this is displayed in a web browser like this:

💡

If you control your Hugo content files, it’s safe to specify unsafe: true in your Hugo config file.

 

This is an example of using an AsciiDoc admonition⁠[4] in an article that’s written in Markdown (which is pretty cool IMHO⁠🆒⁠😎).

 

Shortcode example 2: Use a GoAT diagram in an AsciiDoc content file

Starting with Hugo v0.93.0, Hugo has a built-in Markdown render hook for GoAT diagrams⁠[5] in Goldmark-⁠flavored Markdown⁠[6] using, for example, syntax like this:

```goat
+--------+   +--------+    +-----------+
|  GoAT  |   | Hugo’s |    |           |
| Markup |   |built-in|    |    SVG    |
|   in   | --+  GoAT  +--> |    in     |
| source |   | render |    |destination|
|        |   |  hook  |    |           |
+--------+   +--------+    +-----------+
```

 

To use the above syntax in an article written in AsciiDoc, you can use the renderas shortcode like this:

{{< renderas goldmark >}}

```goat
+--------+   +--------+    +-----------+
|  GoAT  |   | Hugo’s |    |           |
| Markup |   |built-in|    |    SVG    |
|   in   | --+  GoAT  +--> |    in     |
| source |   | render |    |destination|
|        |   |  hook  |    |           |
+--------+   +--------+    +-----------+
```

{{< /renderas >}}

 

Here is how the above is rendered in this article, which is written in AsciiDoc:

MsGaooriuAknrTucpebHuruiGehglonootAdo’-TeksirndestSiiVnnGation

 

Note that the generated SVG (scalable vector graphic) is embedded in the destination file (which, for this article, is hugo-⁠renderstring/index.html).📈

 

More renderas examples

For more examples that use this renderas shortcode, see Infinite Ink’s Comparing Hugo’s Markup Languages (featuring a renderas shortcode)⁠⚖️.

 

References

 

See also

For more about Hugo, see Infinite Ink’s…

 

Endnotes

1. Many Infinite Ink pages, including this one, are evergreen 🌲 and regularly updated.
2. Hugo layout files are written in Go HTML, which is also known as the Go template language.
3. A dictionary is sometimes known as a map. Details are at gohugo.io/functions/dict/.
4. In technical writing, an admonition is also known as an alert. To learn about AsciiDoc admonitions, see docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/.
5. GoAT means Go ASCII Tool. Details are at gohugo.io/content-management/diagrams/.
6. As of Hugo v0.60.0, Goldmark is Hugo’s default Markdown renderer.

Please share & discuss 📝 👎 👍 📯