« MathJax Kitchen Sink
  
Hugo’s .RenderString Method »

AsciiDoc Passthroughs, Hugo, LaTeX, and MathJax on Infinite Ink
Updated  2022-October-7

Page contents

News

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

 

Overview

In this article, I describe how I write and render mathematics on the Infinite Ink website in 2021+.

 

Goals

This section describes the goals I had while developing the system that I now use to publish mathematics on the Infinite Ink website.

 

1. Use MathJax to display mathematics on Infinite Ink

I want to use the newest MathJax JavaScript display engine to render LaTeX markup on any Infinite Ink page…

 

2. Minimize tools and code

I want to use a minimal number of…

 

3. Use MathJax defaults

I want to use the MathJax default settings as much as possible. For example, I use the following MathJax 3 default TeX and LaTeX math delimiters.

  • Inline Display

    • \(will be processed by MathJax\)
  • Block Display

    • \[
      will be processed by MathJax
      \]
    • $$
      will be processed by MathJax
      $$

 

💡

The following multi-⁠line syntax is also rendered inline.

\(
will be processed by MathJax
\)

The delimiters \( and \) are the important parts.

 

AsciiDoc source files

In Hugo, if a content source file name ends with .ad or .adoc,⁠[2] Hugo uses the Asciidoctor Ruby gem to help generate its HTML output file. To learn about this, see Hugo’s Markup Languages: AsciiDoc, HTML, Markdown, Org-mode, Pandoc, and reStructuredText.

 

Front matter: Use mathjax parameter

In an article that includes LaTeX markup, I include mathjax: true in its YAML front matter:

---
# BEGIN Hugo front matter
⋮
mathjax: true
⋮
# END Hugo front matter
---

main matter that contains LaTeX markup

Note that mathjax is a user-⁠defined Hugo variable (not a built-⁠in Hugo variable).

 

Main matter: Use AsciiDoc +++ and ++++ passthroughs

AsciiDoc supports the following passthrough macros.

  • Inline Display

    • pass:[will not be processed by Asciidoctor]

    • +will not be processed by Asciidoctor+

    • +++will not be processed by Asciidoctor+++

  • Block Display

    • ++++
      one or more lines that
      will not be processed by Asciidoctor
      ++++

 

To passthrough…

  • …inline LaTeX markup, I use the +++ macro.

  • …block LaTeX markup, I use the ++++ macro.

Examples are below.

 

Go HTML templates

Hugo’s template language is Go HTML, which is also known as the Go Template language. For details, see pkg.go.dev/text/template and pkg.go.dev/html/template.

 

script in Go HTML head

In the <head> of Infinite’s Ink’s Go HTML layout file, I include the following.

{{ if .Params.mathjax }}
<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script id="MathJax-script" async
        src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js">
</script>    
{{ end }}

 

The first and last lines are Go Template code. The four emphasized lines are suggested on www.mathjax.org/#gettingstarted.

 

noscript in Go HTML body

In the <body> of Infinite’s Ink’s Go HTML layout file, I include the following.

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

{{ "WARNING: 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 }}

 

To learn about Hugo’s RenderString function, see…

 

Examples

The LaTeX examples in this section will not render if you have JavaScript turned off in your web browser.

 

Example 1: Block display

AsciiDoc source

content/path/filename.adoc
The LaTeX logo is:

++++
$$
\LaTeX
$$
++++

 

HTML generated by Hugo with help from Asciidoctor

public/path/filename.html
<p>The LaTeX logo is:</p>
$$
\LaTeX
$$

 

Example 2: Inline display

AsciiDoc source

content/path/filename.adoc
Asciidoctor, Hugo, +++\(\LaTeX\)+++, and MathJax are FLOSS and, respectively, cost $0, $0, $0, and $0!

 

HTML generated by Hugo with help from Asciidoctor

public/path/filename.html
<p>Asciidoctor, Hugo, \(\LaTeX\), and MathJax are FLOSS and, respectively, cost $0, $0, $0, and $0!</p>

 

Rendered by your web browser with help from MathJax scripts

Asciidoctor, Hugo, \(\LaTeX\), and MathJax are FLOSS and, respectively, cost $0, $0, $0, and $0!

 

💡

The following multi-⁠line AsciiDoc source code also renders the above sentence.

Asciidoctor, Hugo,
+++
\(
\LaTeX
\)
+++,
and MathJax are FLOSS and, respectively, cost $0, $0, $0, and $0!

In other words, the in-⁠line mathematical markup that is in the source does not need to be in one line.

 

See also

For more about MathJax, see Infinite Ink’s…

 

Endnotes


1. Many Infinite Ink articles, including this one, are evergreen and regularly updated.
2. Starting with Hugo v0.74.0, the content file extensions that signify AsciiDoc markup are .ad and .adoc (but not .asciidoc). This is a bug.

Comments 📝 🤔 👎 👍

Your comment might immediately improve this page or help me to (eventually) improve this page. To post or view comments, click this paragraph.