Tips and tricks for Github Pages

This blog has been hosted on Github Pages for a long time, a very very long time, according to my git history since Feb 2012 (before that it was on Wordpress).

I decided to make the change for a few reasons:
-To learn something new (Jekyll/Liquid were new to me)
-Have it feel more like a dev blog (writing posts in a dev IDE pushing to git etc.)
-Also the Pretzel Code52 project had just kicked off and I was interested in getting involved in that (https://github.com/Code52/pretzel).

Now, 8 years later I am trying to get into blogging again so I am breathing new life into my Github Pages blog as well as building a new website for a podcast using Github Page so I thought I’d share some of the interesting things it can do.

Docker

I’m not a ruby developer and I didn’t want to have to install all of the ruby dev tools just to be able to add blog posts. Previously I was using a prebuilt version of pretzel locally which worked pretty well, there were a few things that worked differently or were not supported but I got by. After doing a fair bit of work with docker I figured I should just be able to run jekyll on docker, run the same version that runs on Gihub Pages without all the overhead.

Luckily there are already github pages images setup so I didn’t need to do much to get this working, the one I went with is Starefossen/docker-github-pages. After finding that it was as easy as creating a powershell script to run it, which also mounts the directory to the docker container so it will auto update when changes are made.

docker run -it --rm -v ${PWD}:/usr/src/app -p "1000:4000" starefossen/github-pages jekyll serve -d /_site --drafts --watch --force_polling -H 0.0.0.0 -P 4000

For each loops

Github pages and Jekyll use the Liquid templating language which lets you do some fun things, one of them is for loops. The below code loops through the posts on the site (getting the first 12) to display links for each. {% for post in site.posts limit: 12 %} - site.posts being the collection to iterate over. for post in defines a post as the individual item being iterated. limit: 12 sets the loop to only iterate over the first 12 items, this can also be used with offset: 12 which sets the iteration to start at item 12 in the collection.

{% for post in site.posts limit: 12 %}
    <a href="{{ post.url }}">
        {{ post.title }}
    </a>
{% endfor %}

Combine and Minify CSS

This one is a bit of a hack but it allows you to combine and (somewhat) minify CSS files using some of the liquid templating. Starting with the capture block which lets you store a result in a variable without rendering it. Using the capture we then include the relevant css files inside the capture here using the include_relative tag. Finally we render the newly captured variable making sure to strip out the new lines and multiple spaces.

---
permalink: /css/dkdev.min.css
---
{%- capture sitecss -%}
    {% include_relative bootstrap.min.css %}
    {% include_relative fontawesome-free.min.css %}
    {% include_relative clean-blog.css %}
{%- endcapture -%}
{{- sitecss | strip_newlines | replace: "  ", "" -}}

Data files

Jekyll allows you to add other data files that can be used by various pages. These are just yml, json or csv files that can be put in the _data folder that can be accessed from any page or layout using site.data.

- name: Phili J Fry
  title: Delivery Boy

- name: Bender
  title: Company Chef

- name: Turanga Leela
  title: Captain

- name: John Zoidberg
  title: Staff doctor

This data file can then be used by a for loop to display all the items:

{% for character in site.data.characters %}
    <li>
        {{ character.name }} - {{ character.title }}
    </li>
{% endfor %}

Syntax Highlighting

Github Pages has built in syntax highlighting that uses the Rouge Ruby syntax highlighter library. It let’s you wrap your code with {% highlight %} and {% endhighlight %} and it will do some formatting with it which allows you to easily style it. All you need to do is include a rouge or pygments compatible stylesheet.

Here is what mine looks like for reference: https://dkdevelopment.net/css/pygments_style.css