Tips and tricks for Github Pages

Some tips and tricks I have picked up over the years using Github Pages.

Posted by Damian Karzon on 26 July, 2020

This blog has been hosted on Github Pages for a long time, a very very long time, acording 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.

Luckly 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 mounths the directory to the docker container so it will auto upate 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

Gihub 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 %}

Data files

Jekyll allows you to add other data files that can be used by vaious 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:

.highlight pre {
    display: block;
    padding: 9.5px;
    margin: 0 0 10px;
    font-size: 13px;
    line-height: 1.42857143;
    color: #d6deeb;
    word-break: break-all;
    word-wrap: break-word;
    background-color: #141414;
    border: 1px solid #ccc;
    border-radius: .5em;
    border: .3em solid #545454;
    box-shadow: 1px 1px 0.5em #000 inset;
}

.highlight .hll { background-color: #ffffcc }
.highlight .c { color: #637777; font-style: italic } /* Comment */
.highlight .err { color: #d6deeb } /* Error */
.highlight .esc { color: #d6deeb } /* Escape */
.highlight .g { color: #d6deeb } /* Generic */
.highlight .k { color: #569cd6; } /* Keyword */
.highlight .l { color: #d6deeb } /* Literal */
.highlight .n { color: #fff } /* Name */
.highlight .o { color: #7fdbca } /* Operator */
.highlight .x { color: #d6deeb } /* Other */
.highlight .p { color: #d6deeb } /* Punctuation */
.highlight .ch { color: #637777; font-style: italic } /* Comment.Hashbang */
.highlight .cm { color: #637777; font-style: italic } /* Comment.Multiline */
.highlight .cp { color: #7fdbca } /* Comment.Preproc */
.highlight .cpf { color: #637777; font-style: italic } /* Comment.PreprocFile */
.highlight .c1 { color: #608b4e; } /* Comment.Single */
.highlight .cs { color: #637777; font-style: italic } /* Comment.Special */
.highlight .gd { color: #d6deeb } /* Generic.Deleted */
.highlight .ge { color: #697098; font-style: italic } /* Generic.Emph */
.highlight .gr { color: #d6deeb } /* Generic.Error */
.highlight .gh { color: #82b1ff } /* Generic.Heading */
.highlight .gi { color: #d6deeb } /* Generic.Inserted */
.highlight .go { color: #d6deeb } /* Generic.Output */
.highlight .gp { color: #d6deeb } /* Generic.Prompt */
.highlight .gs { color: #addb67; font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #d6deeb } /* Generic.Subheading */
.highlight .gt { color: #d6deeb } /* Generic.Traceback */
.highlight .kc { color: #82aaff } /* Keyword.Constant */
.highlight .kd { color: #c792ea; font-style: italic } /* Keyword.Declaration */
.highlight .kn { color: #c792ea; font-style: italic } /* Keyword.Namespace */
.highlight .kp { color: #c792ea; font-style: italic } /* Keyword.Pseudo */
.highlight .k-Psuedo { color: #c792ea; font-style: italic } /* Keyword.Psuedo */
.highlight .kr { color: #4EC9B0; } /* Keyword.Reserved */
.highlight .kt { color: #569CD6 } /* Keyword.Type */
.highlight .ld { color: #d6deeb } /* Literal.Date */
.highlight .m { color: #CE9178 } /* Literal.Number */
.highlight .s { color: #CE9178 } /* Literal.String */
.highlight .na { color: #9CDCFE } /* Name.Attribute */
.highlight .nb { color: #CE9178 } /* Name.Builtin */
.highlight .nc { color: #4EC9B0 } /* Name.Class */
.highlight .no { color: #d6deeb } /* Name.Constant */
.highlight .nd { color: #d6deeb } /* Name.Decorator */
.highlight .ni { color: #d6deeb } /* Name.Entity */
.highlight .ne { color: #d6deeb } /* Name.Exception */
.highlight .nf { color: #D7BA7D } /* Name.Function */
.highlight .nl { color: #569cd6 } /* Name.Label */
.highlight .nn { color: #4EC9B0 } /* Name.Namespace */
.highlight .nx { color: #d6deeb } /* Name.Other */
.highlight .py { color: #d6deeb } /* Name.Property */
.highlight .nt { color: #569CD6 } /* Name.Tag */
.highlight .nv { color: #d6deeb } /* Name.Variable */
.highlight .ow { color: #7fdbca } /* Operator.Word */
.highlight .w { color: #d6deeb } /* Text.Whitespace */
.highlight .mb { color: #ecc48d } /* Literal.Number.Bin */
.highlight .mf { color: #ecc48d } /* Literal.Number.Float */
.highlight .mh { color: #ecc48d } /* Literal.Number.Hex */
.highlight .mi { color: #ecc48d } /* Literal.Number.Integer */
.highlight .mo { color: #ecc48d } /* Literal.Number.Oct */
.highlight .sa { color: #ce9178 } /* Literal.String.Affix */
.highlight .sb { color: #ce9178 } /* Literal.String.Backtick */
.highlight .sc { color: #ce9178 } /* Literal.String.Char */
.highlight .dl { color: #ce9178 } /* Literal.String.Delimiter */
.highlight .sd { color: #ce9178 } /* Literal.String.Doc */
.highlight .s2 { color: #ce9178 } /* Literal.String.Double */
.highlight .se { color: #ce9178 } /* Literal.String.Escape */
.highlight .sh { color: #ce9178 } /* Literal.String.Heredoc */
.highlight .si { color: #ce9178 } /* Literal.String.Interpol */
.highlight .sx { color: #ce9178 } /* Literal.String.Other */
.highlight .s-Quote { color: #d9f5dd } /* Literal.String.Quote */
.highlight .sr { color: #ce9178 } /* Literal.String.Regex */
.highlight .s1 { color: #ce9178 } /* Literal.String.Single */
.highlight .ss { color: #ce9178 } /* Literal.String.Symbol */
.highlight .bp { color: #d6deeb } /* Name.Builtin.Pseudo */
.highlight .fm { color: #82aaff } /* Name.Function.Magic */
.highlight .vc { color: #d6deeb } /* Name.Variable.Class */
.highlight .vg { color: #d6deeb } /* Name.Variable.Global */
.highlight .vi { color: #d6deeb } /* Name.Variable.Instance */
.highlight .vm { color: #d6deeb } /* Name.Variable.Magic */
.highlight .il { color: #f78c6c } /* Literal.Number.Integer.Long */