Blog migration

This GitHub Page blog was originally set up with the help of my friend and was forked from his repository. The blog went 404 in August last year, and now that I have time, I decide that I should rebuild the site by myself from scratch since the old site has so much excess baggage that I neither use nor understand, which probably contributed to the reason why I accidentally made it disappear in the first place. The attempt was successful, so I want to record the process in this post.

Migration

I chose the Minimal Mistakes theme by Michael Rose. (I stumbled upon the creator from this bilingual (EN-TH) Jekyll math blog) To “migrate” to this new theme, I mainly follow two sources:

• Programming Historian has a beginner-friendly guide to build a GitHub Page site with Jekyll, as in they will tell you things like “Don’t enter a new command before the previous one finishes running” so you can follow the guide easily even if you are clueless about command lines, for example.
• This Stack Overflow answer by Daniel A. A. Pelsmaeker gives a complete rundown on how to switch an existing Jekyll GitHub Page site to a new theme. In the end I had to commit a terrible Git sin of merging completely different branches using --allow-unrelated-histories but that’s fine.

Some random problems that I encountered:

• When running the site locally using bundle exec jekyll serve, make sure to use http and not https (which most browsers usually assume is what you want).
• In the final git push, I received an error

    fatal: HttpReqestException encountered.
    Remote "origin" does not support the LFS locking API.
    Git credentials for https://github.com/[GitHub Page site].git not found.
  

  After installing Git Credential Manager for Windows (1.20.0), git push still prompt failed authentication but after enough failures it just works.

While my old site used Redcarpet, this site uses kramdown, which I suspect is the reason some markdown elements in my old posts stop working. But all in all, they only need slight adjustment (like line breaks in appropriate places) to start working again.

Customization

Pages

Create a folder called _pages, inside which create a markdown file with the following front matter

---
layout: single
title: [the title you want]
permalink: /about/
---

Then tell the theme to make a link to the page in the top navigation bar in _data/navigation.yml by adding

- title: "About"
	url: /about/

Favicon

The favicon (which incidentally shows a capybara, not a lemming) are generated using https://realfavicongenerator.net/ (as recommended in _includes/head/custom.html). Choose “I cannot or do not want to place favicon files at the root of my web site” and enter /asset/[your image folder name] as the location. Download and unzip the package in the image folder and place the code snippet provided by the website in _includes/head/custom.html.

MathJax

This site uses MathJax (2.7.7) and tex2jax to create beautiful equations with minimal effort (unlike bare bone Wordpress LaTeX support). The only file that controls MathJax is _includes/scripts.html where I put the following codes for

• Latex macros (the example showing macros for the quantum mechanical bra-kets)
• in-line math delimitor $...$ (instead of the default \\(...\\))
• equation numbers

<!-- Customize this part for LaTeX macros.-->

<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  tex2jax: {inlineMath: [["$","$"],["\\(","\\)"]]},
  TeX: {
    Macros: {
      ket: ["{\\left| {#1} \\right\\rangle}",1],
      bra: ["{\\left\\langle {#1} \\right|}",1],
      ketbra: ["{\\left|{#1}\\vphantom{#2}\\right\\rangle\\!\\left\\langle{#2}\\vphantom{#1}\\right|}",2],
			av: ["{\\left\\langle{#1}\\right\\rangle}",1],
    }
  <!-- extensions: ["autoload-all.js"]-->
  }
});
</script>

<!-- for $...$ delimitor -->

<script type="text/x-mathjax-config"> MathJax.Hub.Config({ tex2jax: { inlineMath: [['$', '$'],['\\(','\\)'] ], processEscapes: true } }); </script>

<!-- for equation numbers-->

<script type="text/x-mathjax-config"> MathJax.Hub.Config({ TeX: { equationNumbers: {autoNumber: "all"} } }); </script>

To display (say aligned) equations in their own paragraph, use $$\begin{align}...\end{align}$$ for numbered equations

\[\begin{align} \nabla \cdot \mathbf{E} &= 4\pi \rho , \\ \nabla \times \mathbf{E} &= -\frac{1}{c} \frac{\partial \mathbf{B}}{\partial t} , \\ \nabla \cdot \mathbf{B} &= 0, \\ \nabla \times \mathbf{B} &= \frac{4\pi}{c} \mathbf{J} + \frac{1}{c} \frac{\partial \mathbf{E}}{\partial t}. \end{align}\]

or $$\begin{aligned}...\end{aligned}$$ for unnumbered equations

\[\begin{aligned} i\hbar\frac{\partial}{\partial t} \ket{\psi(t)} = H\ket{\psi(t)} \end{aligned}\]

A quick guide on MathJax syntax can be found here.

Popup footnotes

For popup footnotes like this ¹, this site uses Littlefoot.js, a descendent of Bigfoot.js that does not require an additional jQuery. The code snippets in the installation direction needs to be placed in _layouts/default.html. Currently, I do not have MathJax enabled in footnotes. It was possible with Bigfoot using a code by Benjamin Esham, but even that breaks when the formula is too complicated or not supposed to be in-line (for example matrices). So now I avoid using formulas in footnotes in general.

Table of contents

Jekyll can automatically generate table of contents for your posts. This can be done easily by entering toc: true in the front matter of that post. However, what stumped me at first was that to do this you have to be using the single layout, not posts!

1. Alan Jacobs, “The Technology of a Better Footnote,” The Atlantic, March 2012. ↩