Jekyll and Mathjax: How to configure specific inline and display math

1

Hi, I tried to render inline math (with “$`”) and math block (below) with a tick, as it is the preferred Github-flavored markdown (for preview), to publish on GH pages.

```math
E = m c^2

But the equation is not rendered on the GH page, although I already set the _includes/head-custom.html as follows (called in _layouts/defaults.html). I used the default primer theme from GH pages.

<script type="text/javascript" id="MathJax-script" async
  src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js">
  </script>

<script>
  MathJax = {
    tex: {
      inlineMath: [['$', '$'], ['$`', '`$'], ['\\(', '\\)']],
      displayMath: [['```math', '```'], ['$$', '$$'], ['\\[', '\\]']]
    }
  };
</script>

Is there any way to address this issue?

2

Not sure about how to fix that, but when building a page with jekyll, the code markdown line will be replaced by something else, so by the time that the MathJax script runs, the

```math
E = m c^2
```

block will be something completely different.

I would suggest you don’t replace the default inlineMath and use 2 dollar signs, as $$E = m c^2$$ instead.

3

Is it preferred? The documentation just says that ```math is an alternative. Since $$ works both with kramdown + MathJax and in Github flavoured Markdown, it seems to be the easier solution. As @george-gca says, by the time the MathJax JavaScript sees the question, the triple-backtick fence is gone.

4

Yes; in my experience, both $ or $$ will struggle with some Mathjax expressions, particularly when using {}, _, and \hat.

So using $` and ```math is preferred.

5

This documentation is from GitHub. You are not rendering it using the GitHub markdown parser, you are using Jekyll. This documentation is for when you are rendering math blocks on GitHub itself. In your case you are building your page with Jekyll and then publishing to GitHub pages, which is different.

6

Yes, I was questioning if GitHub-flavoured Markdown really prefers fenced code blocks for math, and the documentation I linked to just says that it’s an alternative, and not preferred.

7

So, that is why I am asking for, how to do that in Jekyll.

For reference, here are examples of why I said the use of backtick is preferred:

  1. mathjax - How to create multi-line equation blocks in GitHub? - Stack Overflow
  2. math in markdown failed rendering · community · Discussion #41087 · GitHub
8

Yes, but again, these uses are inside GitHub’s own markdown. Jekyll doesn’t necessarily supports this. And you can change that behavior if you want. For instance, in our template we added support for other fenced blocks, like echarts.

Being clearer: when you build your site with Jekyll and upload to GitHub pages, you are not using GitHub’s markdown parser, you are using Jekyll’s. And all examples here point to someone trying to display math inside a GitHub markdown, like in a README.md file, not inside a GitHub page that is displayed as your-page.github.io. MathJax doesn’t handle itself the math fenced block. It was something added by the GitHub team to their markdown parser. If you check MathJax documentation there’s nothing about math fenced blocks.

Now, why this

displayMath: [['```math', '```']

doesn’t work? Because Jekyll build takes place before Javascript even has the chance to look at the code. So, by the time this fenced block:

```math
E = mc^2
```

gets to the Javascript, means Jekyll built the site, it gets like this:

<div class="code-display-wrapper">
  <pre>
    <code class="language-math">E = mc^2</code>
  </pre>
</div>

Now, if you use

$$
E = mc^2
$$

it correctly converts to

image

Note: as stated in MathJax docs:

By default, the TeX processor uses the LaTeX math delimiters, which are \(...\) for in-line math, and \[...\] for displayed equations. It also recognizes the TeX delimiters $...$ for displayed equations, but it does not define $...$ as in-line math delimiters. That is because dollar signs appear too often in non-mathematical settings, which could cause some text to be treated as mathematics unexpectedly. For example, with single-dollar delimiters, “… the cost is $2.50 for the first one, and $2.00 for each additional one …” would cause the phrase “2.50 for the first one, and” to be treated as mathematics since it falls between dollar signs.

So, changing to $ delimiters might be a bad idea. You should use the default $$.