Tingkai Liu | Notes on Customizing Jupyter and Jekyll

After some struggle I managed to get a custom Jekyll and Jupyter Notebook Layout with the following features:

Custom text fonts (I used “Latin Modern Roman” from Font Squirrel)
Custom MathJax font (this took me a LOOOONNGGGGG time to get on Jupyter)
Automatic Numbering of Paragraphse (taken from this useful issue)
Matlab Kernel for Jupyter Notebook

Examples of the results are as follows:

NOTE: The post uses Anaconda2,Python3.5,pip3,MATLAB2016,Jekyll 3.6.2,Jupyter 4.4.0

Jekyll

Note: all folders are with respect to my-website.github.io/ as root.

I started out with Jekyll modifications, which is much easier than that of Jupyter Notebook. To achieve this customization, all you need to do are the following:

Text Fonts

Download custom font otf and place in the directory /assets/fonts/your-custom-font. Note that you don’t have to do this (you can use cdn directly, but I chose to do this because I think this gives better performance).
Specify custom @font-face in your css file like the following:

@font-face {
    font-family: "Latin Modern";
    src: url(fonts/Latin-Modern-Roman/lmroman10-regular.otf);
}
@font-face {
    font-family: "Latin Modern";
    src: url(fonts/Latin-Modern-Roman/lmroman10-bold.otf);
    font-weight: bold;
}
@font-face {
    font-family: "Latin Modern";
    src: url(fonts/Latin-Modern-Roman/lmroman10-italic.otf);
    font-style: italic;
}
@font-face {
    font-family: "Latin Modern";
    src: url(fonts/Latin-Modern-Roman/lmroman10-bolditalic.otf);
    font-weight: bold;
    font-style: italic;
}

I am editing directly in my /assets/main.scss. Note that I am using italic and not italic, oblique because that turns all text to default italic.

Specify font in your css like body { font-family: "Latin-Modern", sans-serif;}.

Custom MathJax Fonts

I defined a Jekyll variable math:true/false to specify if a post falls under math category. The /_layouts/post.html file then decides if to include a /_includes/mathjax.html file based on this variable as follows:

 <article class="post" itemscope itemtype="http://schema.org/BlogPosting">
     [...]
   {% if site.disqus.shortname %}
     {% include disqus_comments.html %}
   {% endif %}
     [...]
   {% if page.math != false %}
     {% include mathjax.html %}
   {% endif %}
 </article>

In file /_includes/mathjax.html, I imported the MathJax fron https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js?config=TeX-AMS-MML_HTMLorMML and specified the following configurations (refer to official MathJax documentation for more information):

 <script type="text/x-mathjax-config">
   MathJax.Hub.Config({
     "HTML-CSS": {
         availableFonts: [],
         preferredFont: null,
         webFont: "Latin-Modern"
     },
     TeX: {
         equationNumbers: {
             autoNumber: "AMS"
         },
         Macros: {
             mathcal: "\\mathscr"
         }
     },
     tex2jax: {
         inlineMath: [ ['$','$'], ['\\(','\\)'] ],
         displayMath: [ ['$$','$$'],['\\[', '\\]']  ],
         processEscapes: true,
     }
     });
 </script>
 <script type="text/javascript"
         src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
 </script>

Automatic Numbering

Since I only use this feature for math-related subjects, the configuration is placed in the same file /_includes/mathjax.html:

/* Numbered Sections */
body {
  counter-reset: h2
}
h2 {
  counter-reset: h3
}
h3 {
  counter-reset: h4
}
h2:before {
  counter-increment: h2;
  content: counter(h2) ". "
}
h3:before {
  counter-increment: h3;
  content: counter(h2) "." counter(h3) ". "
}
h4:before {
  counter-increment: h4;
  content: counter(h2) "." counter(h3) "." counter(h4) ". "
}
.footer-heading:before {
  content:""
}

Note that the counter-reset for the body starts from h2, this is because I didn’t want numbering for the post title (which is h1).
Note that I removed counter for .footer-heading after noticing that my name at the bottom of the page is getting numbered too.

Jupyter

The Jupyter Notebook configuration turns out to be much much trickier. The main difficulty lies in the configuration of the MathJax fonts.

Note: I am using python3.5 with Jupyter v4.4.0.

Custom MathJax Fonts

The MathJax that comes bundled in pip does not included all the fonts available to that of regular MathJax (for space reasons). Unfortunately, this customization is not very transparent, and is actually not even open to end-users. To overcome this issue, one need to

Download entire MathJax from source, or just the fonts.
Replace MathJax that comes with Jupyter with the full version. I replaced the entire directory in ~/anaconda2/envs/matlab/lib/python3.5/site-packages/notebook/static/components. Note that I created a Conda env called matlab because I didn’t want to mess up my global jupyter and I strongly recommend you do the same.

Now with the new installation, you can find all the fonts that comes with MathJax in the folder /static/components/MathJax/fonts/HTML-CSS (note that when you spawn a Jupyter notebook, the root folder will by default set to ~/anaconda2/envs/matlab/lib/python3.5/site-packages/notebook/). I happen to like “Latin-Modern” a lot because it is a modernized version of the familiar TeX font, and it works nicely with the “Latin-Modern-Roman” font I used for text.

To use a new font, you would usually invoke the MathJax.Hub.Config({}) Javascript call in your custom.js file somewhere (like in ~/.Jupyter/custom/ folder, which is where Jupyter actually looks for custom javascript and css.) BUT, it is not going to work! This is because, as far as I could tell, the MathJax backend for Jupyter is hardcoded to use only “STIX-Web” font, which is abhorrent in my opinion. To change this setting, you will need to monkeypatch it in the main javascript file at static/notebook/js/main.min.js (starting from line 23551).

[...]
    displayAlign: 'center',
        "HTML-CSS": {
            availableFonts: [],
            imageFont: null,
            preferredFont: null,
            webFont: "Latin-Modern", // change from "STIX-Web"
            styles: {'.MathJax_Display': {"margin": 0}},
            linebreaks: { automatic: true }
        },
    });
[...]

Custom Text Fonts

Same as this section above, except now the CSS file is ~/.Jupyter/custom/custom.css and the fonts folder is in ~/.Jupyter/custom/fonts, or any other folder you choose to create under ~/.Jupyter/custom/.

Automatic Labeling

Same as this section above, except now the file is in ~/.Jupyter/custom/custom.js.

Matlab Kernel

Using Matlab Kernel with Jupyter Notebook is a fairly stable feature, for details of how to set up please refer to these 2 links:

Matlab’s official document on how to install Matlab’s python kernel.
matlab_kernel for Jupyter Notebook to use Matlab’s Python Kernel as backend