AsciiDoc Passthroughs, Hugo, LaTeX, and MathJax on Infinite Ink
Updated 2021-August-28

Page contents

News

2021-July-23  Published this evolving⁠[1] article.

Overview

In the 1990s, I published some mathematics on the Infinite Ink website and other internet places, such as the sci.math Usenet group. That was before MathML existed and we were all making it up as we went along. Now — in 2021 — it’s much easier to publish mathematics on the internet. In this article I describe how I currently write and render mathematics on the Infinite Ink website.

The way I’m doing this is non-standard and I do not necessarily recommend that others do it this way. I’m still figuring it out!

My goals

1. Use MathJax to display mathematics on Infinite Ink

I want to use the latest 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…

  • Ruby gems,

  • Hugo shortcodes,

  • JavaScript scripts,

  • and metacharacters (for example, I do not want a single dollar sign ($) to be a metacharacter).

 

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

    • \(will be processed by MathJax\)

  • Block

    • \[
      one or more lines that
      will be processed by MathJax
      \]
    • $$
      one or more lines that
      will be processed by MathJax
      $$

 

AsciiDoc source files

In Hugo, if a content source file name ends with .ad, .adoc, or .asciidoctor, 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, & reStructuredText.

 

Front matter: 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 custom Hugo variable (not a built-in Hugo variable).

 

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

AsciiDoc supports the following passthrough macros.

  • Inline

    • pass:[will not be processed by Asciidoctor]

    • +will not be processed by Asciidoctor+

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

  • Block

    • ++++
      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

script in Go HTML head

In the <head> of Infinite’s Ink’s Go HTML⁠[2] 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 four highlighted lines above are suggested on www.mathjax.org/#gettingstarted.

 

noscript in Go HTML body

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

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

 

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.

 

LaTeX block example

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

 

LaTeX inline example

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!

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. Go HTML 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.