How to support latex in GitHub-pages?

Jekyll Problem Overview

I use jekyll to write post and show it in GitHub-pages. My source file is written with markdown.

How can I insert formula into the markdown file?

I don't want to save the formula into an image and load the image in markdown file. I actually want to write latex formula in markdown file directly.

Jekyll Solutions

Solution 1 - Jekyll

Since resources online have changed regarding this question, here's an update on supporting LateX with GitHub Pages.

Note that the closest to Latex rendering without exporting as images and natively supporting it on your Jekyll site would be to use MathJax.

MathJax is actually recommended in Jekyllrb docs for math support, with Kramdown, it also converts it from LaTeX to PNG, more details on it here at the Kramdown documentation

Option 1: Write your equation in MathURL and embed it.

You could write the equation with MathURL, then generate a url that permanently points to the equation, and display this in an <iframe> tag. However, this will stop working if MathURL goes offline.

Option 2: Implement jsMath

jsMath will allow almost LateX like syntax and will be supported in your blog if you have set it up correctly, there is extensive documentation on this.

Option 3: Mathjax (by far the easiest in my opinion)

Many sites have mentioned that Mathjax is considered a successor of jsMath, and is much easier to implement with Jekyll. MathJax is also used by mathematics.stackexchange.com too!

Step 1: Have your site load the script in sites where you want to display math. (usually done in the header)
Optional: Check your markdown parser in _config.yml. redcarpet or kramdown is suggested in this example. Certain parsers like discount will interfere with the syntax but I have a solution below.
Step 2: Write your equations.

Quoting this tutorial by Gaston Sanchez:

> MathJax does not have the exactly same behavior as LaTeX. By default, > the tex2jax preprocessor defines the LaTeX math delimiters, which are > $...$ for in-line math, and \[...\] for displayed equations. It > also defines the TeX delimiters $$...$$ for displayed equations, but > it does not define $...$ as in-line math delimiters.

Read the documentation on the syntax for more details.

Note: Using the raw liquid tag to ensure Markdown parsers do not interfere with MathJax syntax.
While you could escape backslashes (e.g. \\[ \frac{1}{n^{2}} \\])to ensure they are parsed properly, as described by Chistopher Poole's tutorial, this is not always intuitive and looks complicated. A simpler solution would be to use the raw liquid tag to ensure the text is ignored by the Markdown processor and directly output as a static html. This is done with {% raw %} and also {% endraw %}

Here is a code sample:

 {% raw %}
  $$a^2 + b^2 = c^2$$ --> note that all equations between these tags will not need escaping! 
 {% endraw %}

Lastly also ensure that the fonts support displaying LateX as some have issues like font size being too small. Alternatively here are some additional methods like Google Charts and MathML discussed in the latex StackExchange sister site.

Solution 2 - Jekyll

If you used Jekyll in your GitHub pages, you can add

  <script type="text/x-mathjax-config">
    MathJax.Hub.Config({
      tex2jax: {
        skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'],
        inlineMath: [['$','$']]
      }
    });
  </script>
  <script src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML" type="text/javascript"></script>

in the file _includes/head.html, and then your GitHub Pages site will support MathJax

Solution 3 - Jekyll

The easiest way to do this right now is to use the KaTeX auto-render extension.

Simply drop the following into your <head>:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" integrity="sha384-yFRtMMDnQtDRO8rLpMIKrtPCD5jdktao2TV19YiZYWMDkUR5GQZR/NOVTdquEx1j" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js" integrity="sha384-9Nhn55MVVN0/4OFx7EE5kpFBPsEMZxKTCnA+4fqDmg12eCTqGi6+BB2LjY8brQxJ" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js" integrity="sha384-kWPLUVMOks5AQFrykwIup5lo0m3iMkkHrD0uJ4H5cjeGihAutqP0yW0J6dpFiVkI" crossorigin="anonymous" onload="renderMathInElement(document.body);"></script>

Note that this assumes the following delimiters appear in your HTML:

$$\LaTeX code$$   (for display)
\\[\LaTeX code\\] (also for display)
\\(\LaTeX code\\) (for inline)

Note, if using Jekyll, you will need to have the following in your _config.yml:

markdown: kramdown
kramdown:
    math_engine: katex

WARNING: Do not use math_engine: mathjax. It will break this by automatically removing the LaTeX delimiters.

Solution 4 - Jekyll

A while ago I created xhub, a browser extension that allows you to use math in github pages.

Cons:

You have to install the extension.

Pros:

No need to set up any workflow.

Just edit your markdown as usual and use

Display math:
```math
e^{i\pi} + 1 = 0
```
and inline math $`a^2 + b^2 = c^2`$.

(Syntax just like on GitLab.)

Works well on light and dark background.
You can even copy-and-paste the math!

Perhaps worth checking out.

Solution 5 - Jekyll

I would like this to be a comment on daviewales answer but I do not have enough reputation unfortunately. My understanding of that answer is to copy the 3 lines of code into the file <your_repo>.github.io\_site\<postname>\index.html. However, that file seems to get updated each time the corresponding <postname>.md is edited. Is there a more elegant way to always get those lines of code automatically added to the html file, without having to manually edit it every time I want to check an equation?

EDIT: I think this is one solution to the above problem:

What ended up working for me was based off of PeaShooter's response. I made a folder _includes within my _posts folder, and then populated it with a file head.html containing the code from PeaShooter's answer. Then, in the top line of the post below the YAML front matter (i.e. below the second --- line) I put the code {% include_relative _includes/head.html %}

Note that it was important to make the _includes folder not in base folder <your_repo>.github.io, but within the _posts folder. While placing _includes in the base folder did automatically generate the equation, it ruined the formatting for the rest of the website.

Solution 6 - Jekyll

The best way right now IMO is to use the MathJax backend (which is part of kramdown, i.e. available on GitHub Pages) and then use KaTeX on the frontend for rendering. KaTeX is more lightweight and faster than MathJax, which makes it a better fit for a blog theme.

I'm using this technique with great success for my Jekyll theme Hydejack. Feel free to use it on your own site, by doing the following:

In config.yml, set the math engine to mathjax:

kramdown:
  math_engine: mathjax

Add KaTeX to your site and also make sure the following code runs sometime after it has loaded.

const mathBlocks = document.querySelectorAll('script[type^="math/tex"]');
Array.from(mathBlocks).forEach((el) => {
  const tex = el.textContent.replace("% <![CDATA[", "").replace("%]]>", "");
  el.outerHTML = window.katex.renderToString(tex, {
    displayMode: el.type === "math/tex; mode=display",
  });
});

The actual code I'm using is slightly more complicated. You can check it out on GitHub.

Solution 7 - Jekyll

Unfortunately most answers here are outdated nowadays. Github renders your markdown files and uses $ delimiter for inline math and $$, \( and \[ for display math in the generated html.

Therefore to configure MathJax 3 for github pages you must add

<script>
MathJax = {
  tex: {
    inlineMath: [['$', '$']],
    displayMath: [['$$', '$$'], ['\\(', '\\)'], ['\\[', '\\]']],
  }
};
</script>
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

to the file _includes/head-custom.html. You don't need to create or modify the _config.yml file.

I recommend you to use MathJax 3 over KaTeX, because MathJax 3 is not much slower anymore than KaTeX (see https://www.intmath.com/cg5/katex-mathjax-comparison.php) and supports more features (E.g. KaTex cannot handle \label and \eqref (see https://github.com/KaTeX/KaTeX/issues/2003))

If you still want to use https://katex.org/docs/autorender.html you must add

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" integrity="sha384-ZPe7yZ91iWxYumsBEOn7ieg8q/o+qh/hQpSaPow8T6BwALcXSCS6C6fSRPIAnTQs" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js" integrity="sha384-ljao5I1l+8KYFXG7LNEA7DyaFvuvSCmedUf6Y6JI7LJqiu8q5dEivP2nDdFH31V4" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js" integrity="sha384-+XBljXPPiv+OzfbB3cVmLHf4hdUFHlWNZN5spNQ7rmHTXpd7WvJum6fIACpNNfIR" crossorigin="anonymous"></script>
<script>
    document.addEventListener("DOMContentLoaded", function() {
        renderMathInElement(document.body, {
          // customised options
          // • auto-render specific keys, e.g.:
          delimiters: [
              {left: '$$', right: '$$', display: true},
              {left: '$', right: '$', display: false},
              {left: '\\(', right: '\\)', display: true},
              {left: '\\[', right: '\\]', display: true}
          ],
          // • rendering keys, e.g.:
          throwOnError : false
        });
    });
</script>

to the file _includes/head-custom.html. You don't need to create or modify the _config.yml file.

Note: I tried to use github flavored markdown renderer instead of the default renderer for github pages by setting markdown: GFM in the the _config.yml file. This would give you additional features like autolinks ( see https://github.community/t/github-pages-autolinks-fail/129713/4 ). However the GFM markdown renderer seems to create buggy math sections in the HTML which neither MathJax nor KaTeX seem to be able to handle correctly (see https://chrisyeh96.github.io/2020/03/29/mathjax3.html#november-2020-onwards )

Content Type	Original Author	Original Content on Stackoverflow
Question	Samuel	View Question on Stackoverflow
Solution 1 - Jekyll	matrixanomaly	View Answer on Stackoverflow
Solution 2 - Jekyll	PeaShooter	View Answer on Stackoverflow
Solution 3 - Jekyll	daviewales	View Answer on Stackoverflow
Solution 4 - Jekyll	Nico Schlömer	View Answer on Stackoverflow
Solution 5 - Jekyll	Topher	View Answer on Stackoverflow
Solution 6 - Jekyll	qwtel	View Answer on Stackoverflow
Solution 7 - Jekyll	asmaier	View Answer on Stackoverflow

How to support latex in GitHub-pages?

Jekyll Problem Overview

Jekyll Solutions

Solution 1 - Jekyll

Solution 2 - Jekyll

Solution 3 - Jekyll

Solution 4 - Jekyll

Solution 5 - Jekyll

Solution 6 - Jekyll

Solution 7 - Jekyll

Checking if a string is valid json before trying to parse it?

swift How to remove optional String Character

Attributions