Getting this Blog up and Running

This post will guide you through (all of my mistakes) setting up Jekyll with a customized version of Chirpy on Gitlab.

Skip to the end for a tl;dr on how I set it up.¹

Installing Jekyll

This step will (in time) show to be completely redundant, but I started out by forking the Example Jekyll site using GitLab Pages: https://pages.gitlab.io/jekyll

Afterwards I immediately began looking at the available Jekyll themes, instead of running this fork through the Gitlab CI to test if it would even build out of the box. This was probably a mistake.

Selecting a Theme

I ran through the first 2 pages of a list of jekyll themes, and ended up liking Chirpy the most.

As a side-note: I’ve been stalling this blog for ages, trying to do the perfect job: a self-hosted blog on secure infrastructure with a fast and secure FOSS-loving platform to publish on. That first part was slowing me down the most. For that last part I had settled on Ghost, which I would still love to work with in the future.

My point being that I didn’t have time to check out all 23 pages filled with themes, I was moving fast™…

Trouble

Looking through the files that came with the theme, it looked like it would replace most (if not all) of the files that the Jekyll fork provided. To err on the safe side I just pasted the theme over the original Jekyll fork, overwriting everything.

When typing this, it really does read (?) like a terrible idea, and in all likelihood the source of all the trouble to come..

As soon as my changes hit remote, CI fired up its engines for the first time and the blog was being built. Magic!

I hadn’t built anything locally at this point, assuming this would all be smooth sailing and I’d be writing markdown posts in one fell swoop, instantly ready to push to Gitlab for building and publishing. Oh boy, was I wrong…

An Unmovable Object

  Dependency Error: Yikes! It looks like you don't have kramdown-parser-gfm or one of its dependencies installed. In order to use Jekyll as currently configured, you'll need to install this gem. The full error message from Ruby is: 'cannot load such file -- kramdown-parser-gfm' If you run into trouble, you can find helpful resources at https://jekyllrb.com/help/! 
  Conversion error: Jekyll::Converters::Markdown encountered an error while converting '_posts/2019-08-08-text-and-typography.md':
                    kramdown-parser-gfm
             ERROR: YOUR SITE COULD NOT BE BUILT:
                    ------------------------------------
                    kramdown-parser-gfm

First I tried to understand how this thing (Jekyll, Gitlab, CI, ..) even worked (completely missing out on the importance of the .gitlab-ci.yml file). I tried to look the error up, but couldn’t find much to help me along. I aimlessly tried adding kramdown to the list of gem dependencies, but to no avail. I tried changing configuration settings in Jekyll and the theme, naïeve as I was. Nothing seemed to work.

I had been working on solving the error for over an hour with 0 progress before I decided to try to build it locally. I had been playing around with the gem dependencies, so fortunately those were already installed.

Finally I ran:

 bundle exec jekyll build -d public

An Unstoppable Force

I couldn’t resist the title, however unfit it may be :)

It worked! I could finally discovering how the theme actually looked, now that I could see it in action. This also gave me a backup plan to deploy this thing on gitlab pages, by simply pushing the generated html

My problem wasn’t solved though, the build still failed in the Gitlab CI pipeline. I kept reading around on the Gitlab pages wiki to little avail. I now understood the importance of the .gitlab-ci.yml file but still couldn’t get it to build. After a while without progress I decided to stop worrying about Gitlab and started to tweak the theme to my heart’s content and make this blog my own.

Personalizing Chirpy

Now that I finally had Jekyll running locally I could start tweaking the theme. I began by fixing my socials, adding the beautiful gitlab icon is always delightful.

I then made a small PR on the Chirpy repository to prevent a new blanco page from opening when pressing on the email button in the side-panel.

// Creates a blank page in Firefox/Safari
  javascript:window.open('mailto: XXX@YYY.TLD')
// Does not
  javascript:location.href = 'mailto: XXX@YYY.TLD'

I then adjusted the JS behind that button to make it somewhat harder for my email-address to be crawled away of my blog and into spammer databases, I made the following small change:

// Split the email-address up in three parts: 'email[0]'@'end[0]'.'end[1]'
  {\% assign email = site.social.email | split: '@' %}
  {\% assign end = {{email[1]}} | split: '.' %}
// Email parts, assemble!
  javascript:location.href = 'mailto:' + [['{\{ email[0] }}','{\{ end[0] }}'].join('@'),'{\{end[1]}}'].join('.')

Not the most beautiful variable naming, but I’m moving fast™, remember?

Now that the blog was structurally sound, I started adjusting the colors. The dark theme was my favorite, but many of the main colors weren’t a parameter of dark-typography.scss and were spread about throughout other css files in different directories.

To get the look I wanted, I adjusted some variables and added the following new ones:

  /* Adjusts the URL styling */
  --link-hoover-color: #9f0000;
  --link-underline-hoover-color: #7d0808cf;
  
  /* Adjusts Sidebar coloring */
  --nav-link-hoover: #e62c2cd4;
  --nav-link-active: #db1414;
  --social-icon-hoover: #930404;

Afterwards I hard-coded my preference for the dark theme in dual mode. This way the default theme is dark, but the reader is still empowered to switch to the light theme.

// I replaced this:
  {\% if site.theme_mode != "dual" %}
    mode="{{ site.theme_mode }}"
  {\% endif %}
// With this:
  {\% if site.theme_mode == "dual" %}
    mode="dark"
  {\% endif %}

I created an issue in the Chirpy repository on this subject, but sticking to the system preferences of the user seems to be the more standard approach.

I then focussed on the footer, removing some of the author styling and slimming down the credits. To finish off I added a nice quote I heard earlier today in a scene from the first season of Westworld that I really liked:

Now that is some top-notch acting if you ask me!

Publishing a Fearful Page

Now that the blog was beginning to look rather good, I began writing the ‘About’ section, which proved quite the challenge. I don’t find it easy writing about myself. Let alone giving a decent description of who I am as a person.

Anyway, my mind began to drift towards a scary thought: since I have no experience with actually using Jekyll and the like, and I’m also not really fond of using markdown in my work. I began to fear I wasn’t going to enjoy writing on this platform that I’ve been forcing to life..

At this point I began writing my first post while learning the markdown notation more slowly than I’d liked, but I got there eventually. I still don’t fully get the timezone syntax that helps the date figure out when ’now’ actually is, but I did find myself enjoying the act of writing itself.

Deploy

By now I had already started my second post and I could barely contain my urge to start a dozen more posts.

This blogpost did end up being completed last out of the 7 I had started.