This blog has run on WordPress.com for a while, but I have increasingly found its format to be somewhat frustrating, particularly when it comes to quoting code, which is a frequent occurrence in this blog. I prefer to edit in Markdown, which is possible on WordPress.com, but has limitations. I’ve also been keen to embrace version control where possible, and the ability to edit offline is useful, especially while travelling. I’ve therefore taken the step to migrate the blog to GitHub, and use Jekyll. GitHub provides free hosting for Jekyll blogs.

Here, I describe the steps I took to create this blog:

  • Registering with GitHub
  • Creating a special repository for the blog
  • Installing Jekyll on my computer
  • Cloning a template blog
  • Editing the template to create the blog identity
  • Editing index.html, and archive.html
  • Adding Pagination
  • Adding comment fields and counts to posts using Disqus
  • Adding Google Analytics
  • Creating the first blog post
  • Migrating posts from Wordpress

Creating a special repository for the blog

A GitHub Pages repository is like a normal repository, but must be registered with a specific name referring to your GitHub account name, for instance grahampugh.github.io. Instructions for setting up this repository are found at https://pages.github.com/#user-site.

When the repository is set up, you can clone the empty repository to your computer:

$ git clone {{ site.src_url }}

Installing Jekyll on my computer

Installing Jekyll allows you to run a development server on your computer, so that you can easily preview your blog posts as you write them, without having to upload them to GitHub. Installation is easy.

Cloning a template blog

When run from the root folder of your new repository, jekyll build . command builds a template site on your computer. The jekyll build --watch command automatically watches for changes to the files in the current folder, and regenerates the site as necessary. For more details see http://jekyllrb.com/docs/usage/

Editing the template to create the blog identity

The site settings are contained in the root directory, in _config.yml. I edited the file as follows:

# Site settings
title: On The Subject Of Macs
email: g.r.pugh@gmail.com
description: > # this means to ignore newlines until "baseurl:"
    The Blog of a Mac Support Specialist in a UK University
baseurl: "" # the subpath of your site, e.g. /blog
url: "http://grahampugh.github.io" # the base hostname & protocol for your site
twitter_username: GrahamRPugh
github_username: grahampugh

Editing index.html, and archive.html

The default template has a list of blog posts in index.html. I altered this to include the first 50 words of each post:

<p class="post-meta"></p>

I moved the original list-style page to archives/index.html.

Adding Pagination

Pagination enables you to restrict the number of posts visible on the first page of an index or list page, so that the page doesn’t get too long. To set this up, install as follows:

gem install jekyll-paginate

In the _config.yml file, append the following lines:

#pagination
gems: [jekyll-paginate]
paginate: 10
paginate_path: "/page/:num"

The numeric value for the paginate setting can be altered to set the number of items to be listed per page.

An includes file determines how the links to other pages are displayed. This is _includes/pagination.html:

{% if paginator.total_pages > 1 %}
<div class="pagination">
    {% if paginator.previous_page %}
    <a
        rel="prev"
        href="{{ paginator.previous_page_path | replace: 'index.html', '/' | prepend: site.baseurl | replace: '//', '/' }}"
        >&laquo; Newer</a
    >
    {% else %}
    <span>&laquo; Newer</span>
    {% endif %} {% for page in
    (1..paginator.total_pages) %} {% if page ==
    paginator.page %}
    <em>{{ page }}</em>
    {% elsif page == 1 %}
    <a
        href="{{ '/' | prepend: site.baseurl | replace: '//', '/' }}"
        >{{ page }}</a
    >
    {% else %}
    <a
        href="{{ site.paginate_path | replace: 'index.html', '/' | prepend: site.baseurl | replace: '//', '/' | replace: ':num', page }}"
        >{{ page }}</a
    >
    {% endif %} {% endfor %} {% if paginator.next_page %}
    <a
        rel="next"
        href="{{ paginator.next_page_path | replace: 'index.html', '/' | prepend: site.baseurl | replace: '//', '/' }}"
        >Next &raquo;</a
    >
    {% else %}
    <span>Older &raquo;</span>
    {% endif %}
</div>
{% endif %}

This must be referenced in index.html at the point where the links should be displayed (at the end of the list of posts):

{% include pagination.html %}

Finally, for pagination to actually work, the reference to site.posts must be changed to paginator.posts:

{% for post in paginator.posts %}

Adding comment fields and counts to posts using Disqus

Disqus is the most common embedded comment system used with Jekyll blogs. After you register with Disqus, you are provided with a block of code to add to your site template. I created a file at _includes/comments.html with the following content:

{% if page.comments %}
<div id="disqus_thread"></div>
<script type="text/javascript">
    /* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAGE * * */
    var disqus_shortname = "grahamrpugh"; // required: replace example with your forum shortname
    var disqus_developer = 1; // Comment out when the site is live
    var disqus_identifier = "{{ page.url }}";
    /* * * DON'T EDIT BELOW THIS LINE * * */
    (function () {
        var dsq = document.createElement("script");
        dsq.type = "text/javascript";
        dsq.async = true;
        dsq.src = "//" + disqus_shortname + ".disqus.com/embed.js";
        (
            document.getElementsByTagName("head")[0] ||
            document.getElementsByTagName("body")[0]
        ).appendChild(dsq);
    })();
</script>
<noscript
    >Please enable JavaScript to view the
    <a href="http://disqus.com/?ref_noscript"
        >comments powered by Disqus.</a
    ></noscript
>
<a href="http://disqus.com" class="dsq-brlink"
    >comments powered by <span class="logo-disqus">Disqus</span></a
>
{% endif %}

This is referenced in any page where comments should be added. In my case, I’ve added it to the template for blog posts, which is _layouts/post.html:

{% include comments.html %}

Additionally, comments must be enabled in the YAML front matter of each file (including the blog template file and each individual blog file.

You can enable comment counts by adding the following line to the bottom of your default html page template, just before the </body> tag. The default template file is at _layouts/default.html:

<script
    id="dsq-count-scr"
    src="//grahamrpugh.disqus.com/count.js"
    async
></script>

Then, in the index.html and archive/index.html files, add the following code where you wish the comment count of each post to be shown:

<a
    class="post-meta"
    href="{{ post.url }}index.html#disqus_thread"
    data-disqus-identifier="{{ post.url }}"
></a>

Adding Google Analytics

Any website can be registered for Google Analytics, which provides usage statistics for your site. Register your username.github.io site, and then create the file _includes/google_analytics.html, to contain the embed code provided for you by Google. Then, add a reference to _includes/google_analytics.html in your default template, which is at _layouts/default.html:

{% include google_analytics.html %}

Pushing the new repository to GitHub

Once the repository is set up, it can be pushed to the repository as with any git repository:

git push --set-upstream origin master

The site should now be visible at your site URL.

Creating the first blog post

This is the first new post using Jekyll. In the spirit of Git versioning, rather than working on a file in the _drafts folder, I first checkout a new Git branch, and then create the post in the place where it will ultimately reside. The file for the post is created by making a copy of _drafts/template.md:

git checkout -b 2015-11-23-blogging-with-jekyll
cp _drafts/template.md _posts/2015-11-23-blogging-with-jekyll.md

I edited the title in the YAML front matter to Blogging with Jekyll, and created the content.

The kramdown version of Markdown used with Jekyll does not include the quoting of code snippets using the syntax. Code is highlighted between` `…` tags (htmlcan be substituted forbash, yaml, markdown, pythonetc.). If quoting Jekyll Liquid tags (e.g.{% include google_analytics.html %}), one must embed the code in {% raw ... endraw %} tags.

To preview the blog, run the following command:

jekyll serve

Then browse to http://localhost:4000/ and navigate to the new post.

Once satisfied that all is well with the new post and/or any changes made, push the changes, and then go to Github and create a pull request. Review the changes and merge the branch to master to publish the new post.