Hugo's RenderString Function (Featuring “asciidocify” Examples)
Updated 2021-August-11

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 Hugo had a function — let’s call it asciidocify — that converted 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 you can write your layout files in your favorite markup language, along with the Go Template language.⁠[2]

The examples discussed below use RenderString 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. 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. Infinite Ink uses a 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 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>` twisties.  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> twisties. 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 of the 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 👍 👎 📝

Please comment so I know I'm not speaking into the void. Also, your public comment might improve this page or help me to improve this page.🤩