Setting up Jekyll on GitHub

There are already well-written guides for setting up Jekyll on GitHub Pages, and it would be pointless for me to add another. This page is here mostly as a quick reference for myself. See the references at the bottom for actual tutorials.

I think Jekyll is designed to run automatically on GitHub, as long as you are in your website repository (USERNAME.github.io) or in the gh-pages branch in any other repository.

The most important file is called _config.yml, and must be placed in the main directory. If one is using GitHub pages on one’s website repository, it should look like:

markdown: redcarpet
baseurl: ""
exclude: ['README.md']

For any other repository, the baseurl must be modified:

markdown: redcarpet
baseurl: /REPONAME
exclude: ['README.md']

This website itself is created using Jekyll and is hosted on GitHub, so looking at the source may be useful.

To generate the Jekyll site locally run:

jekyll serve --watch --baseurl ""

Typesetting math

See here, here, and here (Internet archive, archive.today) for more (they should be identical).

See this page for the “big picture”. The idea is that we want the Markdown processor to leave potential LaTeX code untouched so that MathJax can access it.

See here for an extensive list of what works and what doesn’t.

Examples

Enter

`\(\int_a^b f(x) \, dx\)`

to obtain \(\int_a^b f(x) \, dx\).

Enter

`\[\begin{aligned}
\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t}
& = \frac{4\pi}{c}\vec{\mathbf{j}} \\
\nabla \cdot \vec{\mathbf{E}}
& = 4 \pi \rho \\
\nabla \times \vec{\mathbf{E}}\, +
\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t}
& = \vec{\mathbf{0}} \\
\nabla \cdot \vec{\mathbf{B}} & = 0 \end{aligned}\]`

to obtain

\[\begin{aligned} \nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} & = \frac{4\pi}{c}\vec{\mathbf{j}} \\ \nabla \cdot \vec{\mathbf{E}} & = 4 \pi \rho \\ \nabla \times \vec{\mathbf{E}}\, + \, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} & = \vec{\mathbf{0}} \\ \nabla \cdot \vec{\mathbf{B}} & = 0 \end{aligned}\]

(modified from Maxwell’s Equations as given here)

References

• See Thomas Bradley’s guide (there are also video tutorials, which can be accessed from that page).

• See also my own Quora post about static page generation.

The content on this page is in the public domain.