Hugo's RenderString Function (featuring asciidocify shortcode)
Updated  2021-December-28

Page contents

News

2021-August-1  Published this evolving⁠[1] article.

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 have often wished that Hugo had a function — let’s call it asciidocify — that would convert AsciiDoc markup to HTML.

 

The RenderString function to the rescue

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

The examples below use the RenderString function to convert AsciiDoc markup to HTML (i.e., to asciidocify).

 

RenderString example

Thanks to the RenderString function, I can use my favorite lightweight markup language, AsciiDoc, in any Hugo layout file (including shortcodes). For example, here is an excerpt of one of Infinite Ink’s layout files:

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

{{ "WARNING: To render the https://www.mathjax.org/[MathJax] markup on this page, enable JavaScript in your web browser." | $.Page.RenderString (dict "markup" "adoc") }}

</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 Infinite Ink 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 layout/ directory, you need to use a Hugo shortcode. I created the following shortcode called renderas that requires one argument (a markup language identifier⁠[3]). Here is that shortcode:

 

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

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

 

renderas adoc (asciidocify) example

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

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

NOTE: Internet Explorer and some other 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 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⁠🆒⁠😎).

 

More renderas examples

For more examples that use this renderas shortcode, see Infinite Ink’s A Way to Compare Hugo’s Markup Languages.

 

See also

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

Comments and questions 📝 👍 👎 🤔

Your public comment or question might immediately improve this page or help me to (eventually) improve this page.