« MathJax Kitchen Sink Hugo’s .RenderString Method »

# AsciiDoc Passthroughs, Hugo, LaTeX, and MathJax on Infinite InkUpdated  2022-October-7

## 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…

• 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 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$$ #### Rendered by your web browser with help from MathJax scripts The LaTeX logo is: $$\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.

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.