Tag Archives: Jekyll

Jekyll development in zsh⤴

from

A recent post on updating jekyll websites deployed on GitHub describes how this was done on a mac. Apple being Apple, and the advancement of technology being what it is, things have changed slightly such that the workflow needs a slight adjustment.

zsh

Recent OSX (now called MacOS) updates have changed the default shell programme from the Bourne Again Shell bash to the extended version of this, the Z Shell zsh. The first impact of this is that the rake command (or any command passing square brackets) doesn’t work any more:

% rake publish["Test update"]
zsh: no matches found: publish[Test update]

This is simply because zsh requires the square bracket characters to be escaped:

% rake publish\["Test update"\]
Configuration file: /your/path/to/GitHub/projectname/_config.yml
D	docs/yyyy/mm/dd/some-files.html
....

Two terminals

When developing, I use two terminal windows in the dev folder – one to do file operations and the like, the other to run a local version of the site while I test. The quick way to get the second window open within your current working directory is to issue this commmand:

% open -a Terminal .

Github/Jekyll site update via Rake⤴

from

I wanted a quick way to provide useful comments on commits made in development of a Jekyll site which is deployed on GitHub. This method offers a couple of rake tasks to first quickly build the site locally, placing the output into the docs folder; then to commit and push the changes to GitHub once you’re happy. All of this code goes in the Rakefile.

Build

require 'rubygems'
require 'rake'
require 'rdoc'
require 'date'
require 'yaml'
require 'tmpdir'
require 'jekyll'

desc "Generate blog files"
task :generate do
  Jekyll::Site.new(Jekyll.configuration({
    "source"      => ".",
    "destination" => "docs"
  })).process
end

You can test your site in your development machine (I’m using a Mac) using a python http server to render the static site thus:

$ rake generate
Configuration file: /your/path/to/GitHub/projectname/_config.yml
$ cd docs/
$ python3 -m http.server

You should place an empty .nojekyll file in the root of your project to tell GitHub not to bother rebuilding the site. You’re just deploying static files to the docs folder. Once you’re ready to deploy, you can publish via rake. The rest of the Rakefile looks like this:

# Usage:
# $ rake
# $ rake generate
# $ rake publish
# $ rake publish["Your comment here"]

desc "Generate and publish blog to master/docs"
task :publish, [:var] => [:generate] do |task, args|
  args.with_defaults(var: 'Commit via Rake')
Dir.mktmpdir do |tmp|
    system "mv docs/* #{tmp}"
    system "git checkout -B master"
    system "rm -rf docs/*"
    system "mv #{tmp}/* docs"
    system "git add ."
    system "git commit -a -m #{args.var.inspect}"
    system "git push origin master --force"
    system "git checkout master"
    system "echo Finished."
  end
end

task :default => :publish

For example, you might publish using this command from the project folder:

$ rake publish["Example updates"]
(in /your/path/to/GitHub/projectname/)
Configuration file: /your/path/to/GitHub/projectname/_config.yml
D	docs/yyyy/mm/dd/some-files.html
....
Reset branch 'master'
Your branch is up to date with 'origin/master'.
[master abcdefg] Example updates
 n files changed, p insertions(+), q deletions(-)
Enumerating objects: r, done.
Counting objects: 100% (nn/nn), done.
Delta compression using up to x threads
Compressing objects: 100% (mm/mm), done.
Writing objects: 100% (mm/mm), 1234 bytes | 123.00 KiB/s, done.
Total mm (delta nn), reused 0 (delta 0)
remote: Resolving deltas: 100% (nn/nn), completed with nn local objects.
To https://github.com/YourGHName/projectname.git
   0aa7f2g..abcdefg  master -> master
Already on 'master'
Your branch is up to date with 'origin/master'.
Finished.

Or if you’re in a hurry, just issue rake to get the default Commit via Rake commit message.

Rendering LaTeX in Jekyll pages⤴

from @ @cullaloe | Tech, tales and imagery

I wanted to render a formula for standard deviation on a page in a site built on Jekyll. Sal Khan’s Khan Academy has tackled a similar problem and developed their own solution. Not only have they done that, but they have made it available to the world under an MIT Licence. That solution is KaTeX.

Described as “The fastest math typesetting library for the web”, it has no dependencies and renders very quickly on all major browsers. The API is simple and openly accessible, with javascript libraries publicly hosted in a CDN. It is also implemented in kramdown, the MIT-licensed markdown parser, which makes it an ideal solution for sites that are built on Jekyll, such as those hosted on github pages.

To implement it in a Jekyll site, the markdown parser should be set in config.yml:

markdown: kramdown

In the <head> section, perhaps in the included file _includes/head.html, add the KaTeX libraries and css:

  <!-- KaTeX -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/katex.min.css" integrity="sha384-zB1R0rpPzHqg7Kpt0Aljp8JPLqbXI3bhnPWROx27a9N0Ll6ZP/+DiW/UqRcLbRjq" crossorigin="anonymous">

  <!-- The loading of KaTeX is deferred to speed up page rendering -->
  <script defer src="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/katex.min.js" integrity="sha384-y23I5Q6l+B6vatafAwxRu/0oK/79VlbSz7Q9aiSZUvyWYIYsd+qj+o24G5ZU2zJz" crossorigin="anonymous"></script>

  <!-- To automatically render math in text elements, include the auto-render extension: -->
  <script defer src="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/contrib/auto-render.min.js" integrity="sha384-kWPLUVMOks5AQFrykwIup5lo0m3iMkkHrD0uJ4H5cjeGihAutqP0yW0J6dpFiVkI" crossorigin="anonymous"
      onload="renderMathInElement(document.body);"></script>

In my implementation, I set a flag in the yaml header of any page that requires \(\LaTeX\), for example:

---
layout: post
title: Render LaTeX in Jekyll pages
date: 2020-06-11 08:24
published: yes
katex: yes
tags:
- Jekyll
- LaTeX
---

Then conditionally output the header code above only in pages that need to load the css and script:


{% if page.katex %}
  <!-- KaTeX -->
  .
  . etc.
  .
{% endif %}

Using it

Having set the katex flag, I can now type LaTeX code either as display (slightly larger and in its own block on the page), or inline:

$$\LaTeX code$$     % (for inline)
\\(\LaTeX code\\)   % (also for inline)
\\[\LaTeX code\\]   % (for display)

The script converts the $$ code above into either \\( inline or \\[ display syntax which is output as html:

<p>\(\LaTeX code\)     % (inline)</p>
<p>\[\LaTeX code\]     % (display)</p>

and renders thus:

\(\LaTeX code\) \[\LaTeX code\]

Example: binomial coefficient

In the markdown for this page, if I type:

\\[
    \binom{n}{k} = \frac{n!}{k!(n-k)!}
\\]

Jekyll and kramdown will output this html:

<p>
\[
    \binom{n}{k} = \frac{n!}{k!(n-k)!}
\]</p>

In the client browser, the KaTeX javascript will render thus: \[ \binom{n}{k} = \frac{n!}{k!(n-k)!} \]

Caveats

Notice this solution does not render from the server side. All of the rendering is done on the client using the javascript loaded in the head of the page. It just does it very, very quickly.