Recipe for a markdown math blog¶

The goal here is to set up a blog which can process math written in the standard \( \LaTeX \) notation within markdown. In particular, the end product should be able to process inline math using \( \) tags, display math using \[ \], and be able to process begin..end blocks.

If you are not looking for that, there are much simpler ways to set up a blog. I would recommend you look at Blogger or Wordpress if you are looking for a simpler setup.

In this tutorial, I will assume that you have some familiarity with with git and with installing software.

Ingredients¶

• git for source control.
• GitHub (or your favorite source control repository service) for an online home of the source code.
• A Python distribution (I use miniconda, but feel free to use Anaconda or a bare bones Python setup). If you use any other method, please replace conda ... with pip ... or whatever is appropriate for the purpose.
• MkDocs as the static site generator. Pros:
  • simple to deploy
  • produces really pretty outputs
  • built on top of Python
  • allows live preview of changes
  • easily customizable
  • open-source
• Material for MkDocs for the material theme.
• Math (currently only MathJax works for begin..end blocks) For rendering mathematical formulas in \( \LaTeX \), we can use either of the following two JavaScript libraries.
  • MathJax: The setup is way simpler.

  • KaTeX: Much faster.

    ToDo: ask how to link Arithmatex and KaTeX for begin..end blocks.

Directions¶

Essentials¶

• Install git, the Python distribution, mkdocs and mkdocs-material.

• Create a repository in GitHub. We shall call it <mathblog> from now on. To the .gitignore add the line site/.
• Clone the repository (git clone <repository-url>) on your local machine.
• In the folder containing the repository, run mkdocs new <mathblog>. This generates all the required files for MkDocs.
• Now enter the <mathblog> directory (cd <mathblog>), and run mkdocs serve &. If you do not have any errors, go to http://127.0.0.1:8000/ in your web browser. You should see the home page of your (to be created) website. If you get the error pkg_resources.DistributionNotFound: The 'mkdocs-material-extensions>=1.0' distribution was not found and is required by the application, then install MkDocs Material Extensions using pip (pip install mkdocs-material-extensions) since there is not conda package for it yet (check!).
• To check if everything is in order, create a folder inside docs/ and create an markdown document within the folder. This file should automatically show in the website.
• Congratulation, we have set up the basic website. From now on, all modifications will be in the mkdocs.yml, so I will not mention this explicitly.

Math¶

We need either MathJax or KaTeX to process \( \LaTeX \). As I mentioned earlier, we shall use MathJax since I have yet to figure out how to process begin..end blocks in KaTeX. The Arithmatex pages do talk about using KaTeX, but these did not work for me.

First, we need to enable the Arithmatex extension.

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true

Now we need to add relevant scripts.

extra_javascript:
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

extra_javascript:
  - js/arithmatex2katex.js
  - https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/katex.min.js
  - https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/contrib/auto-render.min.js

extra_css:
  - css/katex.my.css
  - https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/katex.min.css

(function () {
'use strict';

var katexMath = (function () {
    var maths = document.querySelectorAll('.arithmatex'),
        tex;

    for (var i = 0; i < maths.length; i++) {
      tex = maths[i].textContent || maths[i].innerText;
      if (tex.startsWith('\\(') && tex.endsWith('\\)')) {
        katex.render(tex.slice(2, -2), maths[i], {'displayMode': false});
      } else if (tex.startsWith('\\[') && tex.endsWith('\\]')) {
        katex.render(tex.slice(2, -2), maths[i], {'displayMode': true});
      }
    }
});

(function () {
  var onReady = function onReady(fn) {
    if (document.addEventListener) {
      document.addEventListener("DOMContentLoaded", fn);
    } else {
      document.attachEvent("onreadystatechange", function () {
        if (document.readyState === "interactive") {
          fn();
        }
      });
    }
  };

  onReady(function () {
    if (typeof katex !== "undefined") {
      katexMath();
    }
  });
})();

}());

.katex {
  font-size: 1.1em !important;    /* Smaller fonts for inline math */
}

.katex-display > .katex {
  font-size: 1.21em !important;    /* Larger fonts for display math */
}

.katex-html {
  overflow-y: hidden;
}

Now write some math in your markdown files and test them out. They should render normally.

Extensions and plugins¶

• ToDo For graphs, we use the MkDocs integration for mermaid. I have not been able to get this running. For an example of what it should look like, see here.
• For each of the following plugins, install the plugin, restart the server, and add the necessary entry under plugins in mkdocs.yml. Further description of each plugin can be found in the respective pages.
• Search
• Minification: minifies all *.html files generated by mkdocs build in a post-processing step, stripping all unnecessary characters to reduce the payload served to the client.
• Revision date: adds the date on which a Markdown file was last updated at the bottom of each page.
• Awesome pages: omits the need to specify all pages in the nav entry of mkdocs.yml. For options, see github.com/lukasgeiter/mkdocs-awesome-pages-plugin/ and lukasgeiter/mkdocs-awesome-pages-plugin.

Presentation¶

Now that we are happy with our creation, it is time for us to show our work to the world. Before we go ahead, we commit to our changes using git commit -a and push the commit to the origin using git push.

Now run mkdocs gh-deploy to create a separate branch called gh-pages for our website. Finally, go to the GitHub Pages settings of your repository and choose the source as gh-pages branch. Now our website is live! Check this by visiting the link to your website as shown in your GitHub Pages settings.

Garnishing¶

Extensions¶

The Python Markdown extensions are a set of extrememly useful extensions. For more extensions, see the Extensions pages of SquidFunk's website for Material for MkDocs.

Mermaid

Analytics¶

• If you do not measure, you will not know. In order to measure traffic to our website, I am going to use Google Analytics. In Google Analytics, set up a property for your website.
• Go to analytics.google.com/ and click Set up for free. Give an account name and go to the next page.
• Select Web in the next page
• Give the name and address of your website. It will create a Tracking ID, which we need to include.

  google_analytics:
    - UA-XXXXXXXX-X
    - auto
  

User interaction:¶

• For comments, we can set up a Disqusion board.
• The first step is to set up a Disqus account. If you do not have one, go to Disqus signup, and create a new account. If you have one, simply sign in.
• The second step is to create a Disqus website. Go to Disqus signup, and click on I want to install Disqus on my site, and fill up the form. Now include your Disqus Website Name in the project.

  extra:
    disqus: the-website-shortname
  

  And we are done!

References¶

The links throughout the recipe were immensely helpful for me to set up the website (and create this document). I highly recommend you visit these sources for a better understanding of the processes and to customize the blog according to your tastes.

• MathML considered harmful

Comments