Mathjax in Github pages

4
votes

I have started a new project in Github and as I will need to collaborate with people, I wanted to start a decent documentation. I would like to use Github Pages for this task, but the documentation will need to include many equations, as for instance https://wec-sim.github.io/WEC-Sim/theory.html.

I have read on-line on numerous posts that Mathjax provides a good tool to read equations on browsers and has been linked to Github pages. However, although I tried to follow many different strategies, I have not been able to get my Page to show any equations yet.

You can find my project at https://github.com/enricoande/uuv and the corresponding page at https://enricoande.github.io/uuv/. The page is built from https://github.com/enricoande/uuv/blob/master/docs/README.md.

Initially, I was not able to display equations at all, but could see the text in the Page. Now, I am not even able to see the page. This has happened after adding the file https://github.com/enricoande/uuv/blob/master/docs/_layouts/page.html which reads

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

Is it possible that the reason why I can no longer see my page is that Mathjax is too slow (I have found comments on this regard on-line)? Otherwise, have you got suggestions on what I could do to fix the Page to display the equations?

As you can see I am a beginner with Github pages and html.

Any suggestion is well appreciated as I am now utterly stuck. Thank you for the help!

2
githubgithub-pagesmathjax

2 Answers

2
votes

If I open the referenced JS file at https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML, I see

console.warn('WARNING: cdn.mathjax.org has been retired. Check https://www.mathjax.org/cdn-shutting-down/ for migration tips.')

So check https://www.mathjax.org/cdn-shutting-down/ for detailed migration tips.

Example solution

<script type="text/javascript" async
  src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?...">
</script>
1
votes

If you open the HTML source of your page, you'll notice that it contains nothing but the script tag.

This is expected since your page template is not actually a template -- for that it would have to contain {{ content }} or similar liquid templating tags so that it can pull content from the actual page.

For example, https://github.com/jekyll/jekyll/blob/master/docs/_layouts/page.html has

---
layout: default
---

<section class="standalone">
  <div class="grid">

    <div class="unit whole">
      <article>
        <h1>{{ page.title }}</h1>
        {{ content }}
      </article>
    </div>

    <div class="clear"></div>

  </div>
</section>

You will then have to create an index.html file in your docs folder that starts with 

---
layout: page
---

so that it pulls in the page template (and the script tag).

Try installing jekyll and generating the default site to evaluate good defaults; see the docs for more information on that. Usually, a script tag appears in a head, header or footer template.