Using MathJax with Jekyll

Question

I have a Jekyll blog and I want to use MathJax with it, in the sense that I want to type something like

$$\sum_{n=1}^\infty 1/n^2 = \frac{\pi^2}{6}$$ 

in my markup files and have the correct LaTeX expression generated using MathJax, similar to how it is done on math.stackexchange .

What is the easiest way to do this? I currently have a jsmath.js file (GitHub gist) in my directory and I thought I could have a simple file called mathjs in my _includes with line

 <script src="path/to/jsmath.js></script> 

and enable that in each post through

 {% include mathjs %} 

but this does not work - when jekyll --server , a page is created, but none of the content is displayed.

Am I going to do it right? Is there a better way to use MathJax with Jekyll?

Answer 1

Of course you can use mathjax with Jekyll. To get this working, make sure

• If you write your post in the markdown method, your markdown interpreter does not clog your mathjax entry. The best way to protect it that I found is to always put the math displayed in the <div> elements and the built-in math in the <span> elements that most markdown interpreters will leave alone.

• Is javascript string displayed correctly in HTML source? It’s easier and faster for me to point to CDN mathjax, rather than provide my own copy. Try using a string

  <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>

(These configuration parameters allow you to use more text notation to start your mathematical environment, for example, \begin{equation} , etc.).

Perhaps there is a problem with your jsmath.js script; the CDN version will be faster and probably more reliable. (I have javascript loading in the footer on every page, but of course your inclusion strategy makes sense if you don't want to load javascript when you don't need it.)

Could we help more if you give us a link to your blog? You can see a few examples on my blog (link to installing Jekyll on github too, if that helps).

Answer 2

If you have enough control over the publishing process (for example, you use Jekyll yourself), a simple solution is to switch the markup parser to one that supports TeX. For example, using kramdown :

 gem install kramdown 

Change markdown line in _config.yml to

 markdown: kramdown 

and add something like

 <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script> 

to _layouts/default.html . Now you can simply mark any math in your posts with $$ .

Answer 3

If you use kramdown as your markdown, it's easy. Kramdown has built-in mathjax support.

• Add this before the </head> in your default layout.

   <script type="text/javascript" async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js? config=TeX-AMS-MML_HTMLorMML"></script> 

• Set true to _config.yml , after the line markdown: kramdown .

   mathjax: true 

• Done. For breeding Mathjax

  • inline, use \( ... \) ,

  • use \[ ... \] .

    The only thing you need to pay attention to is backslash escaping when using markdowns, so the delimiters become \\( ... \\) and \\[ ... \\] for built-in and mathematical blocks, respectively.

• Here is an example of the built-in rendering of MathJax \\( 1/x^{2} \\) , and here is the block rendering: \\[ \frac{1}{n^{2}} \\] .

I use this on my blog.

Answer 4

I wrote a blog post on how to set up MathJax a while ago: Latex Math Magic

In essence, you should stop Markdown from messing with MathJax.

I ended up using blocks of code that worked great for me. Therefore, either use at least 4 spaces before writing anything or using a sharp character: ` ; Unfortunately, MathJax skips the <code> tags by default, as it does not want to convert code that it should not.

So, somewhere in your main layout file you need to add a little javascript code:

 MathJax.Hub.Config({ tex2jax: { skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'] } }); 

In addition, we must tell MathJax to ignore non-latex code blocks or regular code blocks:

 MathJax.Hub.Queue(function() { var all = MathJax.Hub.getAllJax(), i; for(i=0; i < all.length; i += 1) { all[i].SourceElement().parentNode.className += ' has-jax'; } }); 

At its point, all of our latex code blocks will have a has-jax string in their class name. Therefore, we can apply a simple style to our css sheets to give it our own style.

 code.has-jax {font: inherit; font-size: 100%; background: inherit; border: inherit;} 

It may not be the best approach, but it has been working on my blog in recent years and I have never encountered any additional problem.

Answer 5

You can try my static blog generator: Jekyde . Jekyde is similar to Jekyll, but it takes good care of LaTeX in the Markdown file. You only need to put your formulas in $ ... $ and $$ ... $$. Jekyde also contains a markdown editor in a browser with a preview of LaTeX.

Answer 6

Some notes before trying any of the following options

Option 0 will increase build time even with --incremental and indeed option 1 should probably be used in most cases, however, this, together with the extra space required, can be costly if you are deploying on the network with clients who may not have access to the CDN.

Both options were tested on a private server with kramdown as the markdown interpreter and mathjax: true set in the _config.yml project _config.yml ; see step 2 Soham Bhattacharya’s answer and his introduction, as well as the first two Karamdir code blocks for instructions on these bits.

Option 0 download and copy the unpacked source to project-name

1. Download source

 cd ~ mkdir -p git/hub && cd git/hub git clone --depth 1 https://github.com/mathjax/MathJax.git 

2. Create a directory path in your project and copy files from MathJax/unpacked along this path

 cd ~ mkdir -p git/lan/project-name/assets/JS_3rd_Party/MathJax cp -r git/hub/MathJax/unpacked/* git/lan/project-name/assets/JS_3rd_Party/MathJax/ 

3. Add source to git tracking

 cd git/lan/project-name/ git add assets/JS_3rd_Party/MathJax git commit -m 'Added MathJax.js unpacked source to git tracking' 

4. Write an include file

 tee ./_includes/MathJax.html 1>/dev/null <<EOF {%- if jekyll.environment == 'production' and site.mathjax == true -%} <script type="text/javascript" src="{{'/assets/javascripts/JS_3rd_Party/latest.js?config=TeX-AMS-MML_HTMLorMML' | relative_url}}"></script> {%- elsif jekyll.environment != 'production' and site.mathjax == true -%} <script type="text/javascript" src="{{'/assets/javascripts/JS_3rd_Party/MathJax.js?config=TeX-AMS-MML_HTMLorMML' | relative_url}}"></script> {%- endif -%} EOF 

Private server assemblies will use MathJax.js where the MathJax.js will be used as the production environment (GitHub) using the latest.js latest.js Liquid if ... elsif ... endif above.

5. Write a post to check it out

 tee ./_posts/$(date +'%Y-%d-%m')-math-tests.markdown 1>/dev/null <<EOF --- layout: post title: "Math Tests" date: $(date +'%Y-%d-%m %H:%M:%S %z') categories: math --- {%- include MathJax.html -%} <span> for $x,y,z \in \{1, 2,\dots 9\}$ </span> <span> $$ \sum_{i=1}^n X_n $$ </span> EOF 

I have not tried this without a <span> because the cboettig suggestion seems to fully help . Additionally, extra lines within the span are an error , without them where there are still problems with the output being displayed.

6. Add these latest git tracking files

 git add _posts/$(date +'%Y-%d-')math-tests.markdown git add _includes/MathJax.html 

7. Build locally or install and build on a remote server

 bundle exec jekyll build --destination /tmp/www/project-name --config _config.yml --incremental 

---

Option 1 copy only latest.js to use CDN (Content Delivery Network)

1. See Option 0 step 1.

2. Create a directory path for third-party JavaScripts scripts and copy MathJax/unpacked/latest.js

 cd ~ mkdir -p git/lan/project-name/assets/JS_3rd_Party/MathJax cp git/hub/MathJax/unpacked/latest.js git/lan/project-name/assets/JS_3rd_Party/MathJax/ 

3. Write an include file

 cd git/lan/project-name tee ./_includes/MathJax.html 1>/dev/null <<EOF <script type="text/javascript" src="{{'/assets/javascripts/JS_3rd_Party/latest.js?config=TeX-AMS-MML_HTMLorMML' | relative_url}}"></script> EOF 

4. See Option 0 Step 5.

5. Add these three files to track git

 git add _includes/MathJax.html git add _posts/$(date +'%Y-%d-')math-tests.markdown git add assets/JS_3rd_Party/MathJax git commit -m 'Added 'MathJax.html', 'latest.js', and a test post to git tracking' 

6. See Option 0 Step 7. for local construction

---

For any of the options

When deploying to a private server, you may also need to define baseurl in your _config.yml project _config.yml , especially if the _config.yml URL scheme is username.tld/project-name , which GitHub uses on your private server.

When deploying both on a private server and on GitHub, it may be better to use a separate configuration file and when building the problem --config _config.yml,_config_baseurl.yml , for example ...

 # Write the special config file tee ./_config_baseurl.yml 1>/dev/null <<EOF baseurl: "project-name" EOF # Build with extra config bundle exec jekyll build --destination /tmp/www/project-name --config _config.yml,_config_baseurl.yml --incremental 

Hope this helps with asset loading through inclusion.

Answer 7

Thank you, I fully understand that I am using this particular thing on my Jekyll website. But I discovered some serious problems, when I implemented this on my site it shows an unwanted script loading.