This is an account of my experience setting up this web site using github pages and jekyll.

It is not a tutorial on the subject, but rather a list of what I did, and why.

At first the intention was to have a set of simple pages summarising some of my projects. The usual github based address https://fredyouhanaie.github.io was sufficient. However, once I took a closer look at the features provided by github pages and jekyll, it was clear that this combination would also be suitable for publishing blog posts.

The github documentation provides instructions on various scenarios for creating a web site, depending on one’s needs. This article shows one particular path that covers the following personal requirements:

  • It should cater for use of plain text for all content, so that they can be version controlled.

  • It should allow use of own domain name with https access.

  • It should be possible to preview the rendered pages locally before deployment to github.

About github pages and jekyll

  • The contents of the web site (github pages) are kept in a git repository that is hosted on github.

  • Github uses jekyll to generate the static web pages.

  • The static web pages are generated from text files (YAML+markdown) that follow a specific format, see https://jekyllrb.com/docs/front-matter/.

  • The html files are generated automatically, through github actions, whenever new changes are pushed to the repository.

Creation and the initial setup of the github pages

This was the first step. It was pretty straightforward. I just followed the instructions here.

After the set up and creation of a simple index.html file, the web site was up and running.

Installing jekyll on a local host (laptop)

jekyll, a ruby based application (a gem), is needed so that we can update and preview the web pages locally. The github docs for installing and configuring jekyll can be found here

I already had ruby installed, so it was just a matter of installing jekyll:

gem install jekyll

I ran the above command as a non-root user (there is no need for root here), this resulted in the files being installed in:

$HOME/.local/share/gem/ruby/3.0.0/gems/jekyll-4.2.2

Rather than adding yet another directory to my $PATH for the jekyll command, I used a symlink as follows:

cd $HOME/.local/bin
ln -sv ../share/gem/ruby/3.0.0/bin/jekyll jekyll

Creation of the basic web pages

Once jekyll was installed, the site scaffold was created within the local repo of the github pages:

jekyll new --skip-bundle .

Next, the Gemfile needed customization, as per the github docs, which consisted of the following two changes:

  • comment out the gem "jekyll" ... line
  • uncomment the gem "github-pages" line, and add the version

Once updated, all the necessary packages were installed by running the bundler, the ruby package/dependency manager:

bundle config set --local path 'vendor/bundle'
bundle install

The bundle config ... command is to force the downloaded gems to be installed locally, rather than in the system directories. The command is what was suggested by the bundler when bundle install was run as a non-root user. The vendor/ directory is not tracked by git – a .gitignore file was generated when jekyll new ... was run.

Normally, we would run bundle exec jekyll serve to generate and preview the web pages, however, since I am using ruby 3.0.x, I also needed an additional package:

bundle add webrick

The above added another entry, gem "webrick" ..., to the Gemfile. Bundler was run again for the new gem:

bundle install

Local preview of the web site

We are now ready to preview the, currently empty, web site:

bundle exec jekyll serve

While the server is running, the web site can be viewed at http://localhost:4000. If we modify any of the contents, such as index.markdown, the modification will be reflected in the web page, of course the browser tab will need a refresh/reload.

Customization

The main configuration of the web site is kept in the _config.yml file. Some of the initial settings are sample site title and author names and email. These needed to be changed.

I configured my own title, name, email etc, followed by a restart of the server.

It should be noted that changes to _config.yml will only take effect when the server is restarted.

Blog posts

Once the web site was operational, the initial base pages, index.markdown and about.markdown, were personalized.

Next, it was just a matter of creating the blog posts in the _posts directory.

Setting up my own hostname and https

I wanted the web site to be accessed through my own domain name, anydata.uk. Again, this was achieved on the github web site, following the instructions here

It required creating two ANAME records, anydata.uk and www.anydata.uk, through my domain name service provider. Both ANAME and CNAME records serve the same purpose, an explanation of the differences can be found on Wikipedia.

When configuring the hostname on Github, a new file, CNAME, was created and committed to the repo by github. Withih the github settings page the box for https was also selected. Naturally, there was a delay before the complete https based web site was available.

The web site is still accessible through the original github address, https://fredyouhanaie.github.io.

Other domain names

I also needed my old hostnames, anydata.co.uk and www.anydata.co.uk, to point to the new web site. However, since github only allows one CNAME per web site, this could only be achieved with an html redirection on the original server.

The _drafts directory and the drafts git branch

Jekyll expects the blog articles to be files in the _posts directory. It will also check for articles in the _drafts directory, provided that the web pages are generated with the --drafts command line option, for example:

bundle exec jekyll serve --drafts

This feature combined with a local/private git branch called drafts (actually any name would suffice here) has enabled me to adopt the following process:

  1. Take new blog ideas (good or bad) and write them in files in the _drafts folder
  2. Track the changes/revisions made to the files with git (drafts branch)
  3. Review the rendered pages locally, edit/update as necessary
  4. Repeat the above until something worth publishing emerges
  5. Copy (not move) the finished article to the _posts directory, ready for publication

The last step involves creating a new file on the main branch, and pushing the changes to github.

Epilogue

For anyone considering a similar project, the supporting documentation provided by Github and Jekyll are pretty good, even for the impatient! The occasional internet search also helps ;-)

So, what’s the point of this article? Well, it provides one specific scenario for anyone in a similar position. And, more specifically, it has allowed me to aquaint myself with the toolset :-)