Test Jekyll themes for GitHub Pages, especially LaTeX
References:
There are two types of GitHub Pages:
username.github.io
: A user's GitHub Pages. It is a separate
repo of the same name i.e. username.github.io
. For example, if
your username is jraman
, then create a repo named
jraman.github.io
.There are multiple ways to configure:
master
branch in the root directory.master
branch in the docs/
directory.gh-pages
branch. Prior to August 2016, it used to be
that this was the only way to configure GitHub Pages for repos,
but not anymore. See this GitHub
blog.In this repo we will use the docs/
director (aka folder).
pip
. A Ruby module
is also called a Gem--get it? :).bundle install
: pip install -r requirements.txt
.
bundle
can also execute a Ruby script in a specific enviroment,
while pip
does not.As you can see, there's lots of languages, types of languages, installers, and package managers in play here.
Check rbenv
installation:
# Run rbenv-doctor
$ curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-doctor | bash
# You may need to run which the following adds ~/.rbenv/shims to PATH and does other things.
$ eval "$(rbenv init -)"
# Display available ruby version. * = active version.
$ rbenv versions
* system
2.7.0 (set by ~/.rbenv/version)
# Set the global ruby version
$ rbenv global 2.7.0
# Check
$ rbenv version
2.7.0
$ ruby -v
2.7.0
gem
, the RubyGems program, is a command-line utility to install
Ruby packages. It "is a sophisticated package manager for the Ruby
programming language" (from the gem
manpage).rake _0.7.3_ --version
will run rake
version 0.7.3 if a newer version is also installed.Jekyll is a static site generator written in Ruby originally by Tom Preston-Werner, GitHub's co-founder in 2008. It is especially suited for blogs (pages with title and date).
_config.yml
. Search on github: extension:yml filename:"_config.yml" language:YAML
.bundle info --path minima
or bundle info --path <theme>
git commit --allow-empty -m "Force rebuild of site"
We follow instructions from GitHub's page titled Creating a GitHub Pages site with Jekyll. Steps are detailed below.
From the GitHub Dependency page,
we find that we need Jekyll 3.8.5. We first install the latest
bundler
and then install the required version of Jekyll.
$ gem install bundler
Successfully installed bundler-2.1.4
Parsing documentation for bundler-2.1.4
Done installing documentation for bundler after 1 seconds
1 gem installed
# The GitHub Dependency page specifies version 3.8.5
# https://pages.github.com/versions/
$ gem install jekyll -v 3.8.5
Successfully installed jekyll-3.8.5
Parsing documentation for jekyll-3.8.5
Done installing documentation for jekyll after 0 seconds
1 gem installed
$ mkdir docs
$ cd docs
# Note the underscores
$ jekyll _3.8.5_ new .
# Check the version of jekyll
$ bundler exec jekyll -v
jekyll 3.8.5
# Start the server, which also monitors and compiles any changes to files on disk.
$ bundle exec jekyll serve
After git push
ing the files, and configuring the
Settings to publish from the master branch, /docs
folder (aka directory), you should see a basic site at
<username>.github.io/<repo>
. For this project, it is
jraman.github.io/test-jekyll-themes/.
Open the Gemfile that was created and follow the instructions in the Gemfile's comments to use GitHub Pages.
# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
# uncomment the line below. To upgrade, run `bundle update github-pages`.
# gem "github-pages", group: :jekyll_plugins
Accordingly, we
gem "jekyll"
line.gem "github-pages"
line.bundle install
. This will print out error messages (in red) and
recommend running bundle update
.bundle update
.We also update the baseurl
in _config.yml
to
/test-jekyll-themes
. And push this and the above changes to GitHub.
That's it!
To view whether the change you pushed has been deployed, go to the
environment
tab, which takes you to a deployments
page.
We maintain separate branches for the different themes, as they may have different configurations and what not.
A useful feature of git is to move (-m
) and copy (-c
) branches.
The capitalized version, -M
and -C
, force move and force copy,
respectively.
We will try the following methodology:
git branch -C theme1 master
git branch -C theme2 master
Themes officially supported by GitHub are here.
The directory structure of your Jekyll files (for example, in docs/
)
looks something like:
|---_config.yml
|---404.html
|---about.md
|---index.md
|---_posts
| |---2020-02-17-welcome-to-jekyll.markdown
|---_site
| |---feed.xml
| (... other files generated by Jekyll that make up the final site)
$$
start and end demarcators in the same line.$$
demarcators in its own paragraph.$$
blocks.
Examples include \begin{equation}
(numbered), \begin{equation*}
(unnumbered),
\begin{align}
, \begin{cases}
.Example MathJax config:
<script>
MathJax = {
tex: {
tags: 'none', // none=no eq numbering, ams=AMS numbering (some), all=all equations
inlineMath: [ // start/end delimiter pairs for in-line math
['$', '$'],
['\\(', '\\)']
],
displayMath: [ // start/end delimiter pairs for display math
['$$', '$$'],
['\\[', '\\]']
],
macros: {
RR: '{\\bf R}', // string replacement
bold: ['{\\bf #1}',1] // macro with one parameter
}
}
</script>
Where does this go? Probably in one of the _includes
files for the
theme. For example, in the So-Simple theme, the file "$(bundle info
--path so-simple 2>/dev/null)/_includes/scripts.html" checks if
mathjax is configured for this site and configures and includes the
required mathjax javascript file.
Example script include:
<script type="text/javascript" id="MathJax-script" async
src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js">
</script>
# output is generated into stdout
$ kramdown _1.17.0_ _posts/2020-02-07-welcome-to-jekyll.markdown
kramdown
inserts <script type="math/tex">
blocks in the output
HTML. While this is fine with the older version of MathJax (2.x), the
newer version (3.x) barfs at it. See the script later below to strip
out these <script>
blocks.
http://docs.mathjax.org/en/latest/upgrading/earlier/jsMath.html
If you are generating your jsMath documents programmatically, it would
be better to convert from generating the jsMath <span> and <div> tags
to producing the corresponding MathJax <script> tags. You would use
<script type="math/tex"> in place of <span class="math"> and <script
type="math/tex; mode=display"> in place of <div class="math">. See the
section on How mathematics is stored in the page for more details.
https://github.com/mathjax/MathJax/issues/2220
As specified in the MathJax ticket (#2220), the following script
strips out the <script type="math/tex">
tags which MathJax 3.x is
unable to handle. We create two separate configurations for MathJax
3.x and 2.x. More
here.
{% if site.mathjax3 == true %}
<script>
// MathJax 3.x
MathJax = {
tex: {
tags: 'ams' // none=no eq numbering, ams=AMS numbering (some), all=all equations
},
options: {
renderActions: {
// for mathjax 3, handle <script "math/tex"> blocks inserted by kramdown
find_script_mathtex: [10, function (doc) {
for (const node of document.querySelectorAll('script[type^="math/tex"]')) {
const display = !!node.type.match(/; *mode=display/);
const math = new doc.options.MathItem(node.textContent, doc.inputJax[0], display);
const text = document.createTextNode('');
node.parentNode.replaceChild(text, node);
math.start = {node: text, delim: '', n: 0};
math.end = {node: text, delim: '', n: 0};
doc.math.push(math);
}
}, '']
}
}
}
</script>
<script type="text/javascript" id="MathJax-script" async
src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
{% endif %}
{% if site.mathjax == true %}
// MathJax 2.x
<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
{% endif %}
Flavors:
gemspec
in your Gemfile
. Do not checkin Gemfile.lock
.Gemfile
and
Gemfile.lock
. Your Gemfile
will not be dependent on
gemspec
. The Gemfile.lock
file notes the exact versions and
sources of every piece of third-party code that was used in the
application.This theme is officially supported by GitHub.
Print out this theme's directory on your computer.
$ bundle info --path jekyll-theme-architect
~/.rbenv/versions/2.7.0/lib/ruby/gems/2.7.0/gems/jekyll-theme-architect-0.1.1
Note that the _layouts
directory in this theme directory has only one html file, namely default.html
post
and page
layouts:index.html
, and not index.md
. If both are present, then index.md
overrides.Layouts:
# Main
default - the main layout. All other page layout are derived from this.
home - derived from page layout.
page - derived from default layout.
post - derived from default layout.
# Pivots
category - derived from page layout.
collection - derived from page layout.
search - derived from page layout.
tag - derived from page layout.
# Collections
categories - derived from page layout.
posts - derived from page layout.
tags - derived from page layout.
Liquid tag start with {%
and end with %}
. For a basic explanation
and examples, see Jekyll docs: Order of
interpretation
Example: String variable, with defaults
<html lang="{{ page.lang | default: site.lang | default: 'en-US' }}"
<script\>... javascript code...</script\>
.<!-- Custom JavaScript files set in YAML front matter -->
{% for js in page.customjs %}
<script async type="text/javascript" src="{{ js }}"></script>
{% endfor %}
# Front matter YAML
---
layout: post
title: Adding custom JavaScript for a specific post
category: posts
customjs:
- http://code.jquery.com/jquery-1.4.2.min.js
- http://yourdomain.com/yourscript.js
---