Hugo’s .RenderString Method (featuring AsciiDoc admonitions in Markdown and Go HTML)
Updated  2022-9-9

Page contents

News

2022-August-1  As of today, this evolving⁠[1] article has been on the web for 1 year.🎂

 

Prerequisites

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

 

Hugo has markdownify but not asciidocify

Since version 0.13, which was released in early 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 this AsciiDoc admonition:

 

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

 

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

 

Infinite Ink’s “render as” 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’s 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 }}

 

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 >}}

NOTE: Internet Explorer and some other web browsers do not support `<details>` accordians.  If you are using one of those browsers, you probably did not need to "`click here`" to see this part of this article.

{{< /renderas >}}

 

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

 

ℹ
Internet Explorer and some other web browsers do not support <details> accordians. If you are using one of those browsers, you probably did not need to “click here” to see this part of this article.

 

This is an example of using an AsciiDoc admonition 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⁠[4] in Goldmark-⁠flavored Markdown⁠[5] 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 A Way to Compare Hugo’s Markup Languages.

 

References

 

See also

For more about Hugo, see Infinite Ink’s…

 

Endnotes

1. Many Infinite Ink articles, 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 also known as a map.
4. GoAT means Go ASCII Tool. Details are at gohugo.io/content-management/diagrams/.
5. As of Hugo v0.60.0, Goldmark is Hugo’s default Markdown renderer.

Discuss or share 📝 🤔 👎 👍 🐘