Introduction

This is the third and final part of a three-post series, where I sum up the journey of building my website. If you haven’t, make sure to read Part 1: Setup and Design Decisions and Part 2: Custom Implementation and Plugins. In this part, the site will finally go live! I will share a useful checklist for pre- and post-publishing, based on my experiences, and we will conclude the series with my final thoughts.

Publishing

At this point, I have implemented what I planned for a minimum viable product (MVP). I have also created one initial post in each of my sub-blogs, so my site was ready to go public.

gh-pages deploy branch

Since I cannot use GHP directly to build my site, I have to build it locally, and push it to a separate branch. I set it up this way.

1. Create an orphan branch called gh-pages.

git checkout --orphan gh-pages
git rm -rf .   # Clean working directory
echo "My site is published here" > index.html
git add index.html
git commit -m "Initial gh-pages commit"
git push origin gh-pages
git checkout main  # Go back to your main branch

An orphan branch means that it has no commit history when created. It is like starting a brand new repository inside the existing one. It is useful, because the gh-pages deployment branch will contain the built site and needs nothing else from the main branch. That’s why the second command cleans the working directory to prevent adding all the existing files to gh-pages.

2. Set GitHub Pages to use the gh-pages branch

• Go to your repo on GitHub -> Settings -> Pages
• Source: Select gh-pages branch, /(root)
• Save.

3. Publishing the website. These are the steps you need to carry out every time you want to publish.

  bundle exec jekyll build

  git worktree add ../_deploy gh-pages

rm -rf ../_deploy/*
cp -r _site/* ../_deploy/
cd ../_deploy
git add .
git commit -m "Publish site"
git push origin gh-pages
cd -

# Set Jekyll to production environment
JEKYLL_ENV=production bundle exec jekyll build

# Continue deployment steps
rm -rf ../_deploy/*
cp -r _site/* ../_deploy/
cd ../_deploy
git add .
git commit -m "Publish site"
git push origin gh-pages
cd -

./deploy.sh

Publishing experiences and checklist

In this section, I will sum up my experiences launching my site. In general, it went quite smoothly without major issues (not that the risk was very high :P), but I want to remember some takeaways for the next time.

Key takeaways

• It was a good idea to do a “soft” launch one day before the “official” launch.
  • “soft” launch: I shared the link with my friends and family asking for feedback. This caught smaller issues and got some improvement ideas for the future.
  • “official” launch: one day later I announced my site on LinkedIn and Instagram

Checklist/steps to do when publishing

1. Build with JEKYLL_ENV=production and run locally (http://127.0.0.1:4000/)

2. Publish

After publishing

After my site has gone live, I have set up a couple of more things.

1. I bought my domain and set it up in GitHub Pages. Now my site is available at https://petertengg.com/
2. Google Search Console: helps monitor how your site appears in Google Search and fix indexing or SEO issues.
3. Google Analytics: tracks and reports website traffic, showing how visitors interact with your site.

I mention them here just for the sake of completeness, but the details are out of the scope of this (already quite long) blog post. If you want me to cover them, let me know and I will be happy to do so.

Conclusion

I feel I have managed to set up a good framework for my further blogging endeavours. It was a relatively big initial investment, but it was totally worth it. I am really satisfied and proud of the result. I got to learn a lot about GitHub Pages, Jekyll and Minimal Mistakes. In hindsight, I am happy to have chosen this path and would do the same if I had to start over. The learning curve of this stack is relatively easy, I had a lot of fun building my site, and the result is satisfying. I also have the feeling that I haven’t reached the limits of this framework, it still offers plenty of room for future improvements. For now, however, I want to enjoy my site and focus on writing posts and publishing content.

Before this, I had very limited experience with web development, and it wasn’t exactly positive either. Jekyll may have been the gateway drug for me to web development. Who knows, maybe next time I will get into dynamic site development as well. But for now, I want to focus on my core areas: C++, (performance) optimisations and trading.

Before dropping the pen, I want to give a shoutout to Minimal Mistakes and its creator Michael Rose. MM proved to be a good choice, even though I don’t have much experience with other themes. Great experience, very well documented, flexible and a lot of fun to work with. Very happy with the outcome.

Links

• Part 1: Setup and Design Decisions
• Part 2: Custom Implementation and Plugins
• Portfolio entry
• GitHub repo

Sources

• Minimal Mistakes documentation and demo site

Introduction

This is Part 2 in a three-post series, where I sum up the journey of building my website. If you haven’t, make sure to read Part 1: Setup and Design Decisions. In this part, I continue with the implementation process. I will show how the amusingly named monkey patching helped me overcome another technical challenge, and we’ll explore how to customise a Jekyll theme to your liking.

The implementation process (continues Part 1)

Since I wasn’t familiar with the Jekyll framework, I explored its capabilities and limitations along the way. The road was a bit bumpy, but it wasn’t too steep, and the process was quite enjoyable.

Related posts - monkey patching (Ruby)

Another limitation of Jekyll’s default behaviour is that it only suggests related posts from the Posts collection which I don’t even use. I had to override it to include all my collections. Here, I took a different approach from the AllTaxonomiesPlugin, because that one creates new collections that don’t exist in Jekyll, but here I wanted to modify Jekyll’s existing behaviour. It uses Classifier Reborn to calculate similarities between posts based on content, not just categories and tags. I wanted to keep that, so I used Ruby’s so called monkey patching technique which allows you to overwrite existing code, without modifying Jekyll’s internal code. (When I first heard monkey patching, I thought it was a joke). The key part of related_posts_patch.rb is this:

module Jekyll
  class RelatedPosts
    ...
    def all_docs
      @all_docs ||= begin
        collections = %w(updates programming cooking portfolio)
        collections.flat_map { |c| site.collections[c]&.docs || [] }
      end
    end
  end
end

all_docs returns all documents across all my collections, and replaces the original site.posts.docs in the code. The rest of the logic is intact.

Overriding and customising Jekyll themes

In the previous chapter, I introduced Jekyll plugins and monkey patching as two means of overriding Jekyll’s default behaviour in Ruby code. These are powerful but relatively advanced techniques, best suited for users comfortable with code. However, these are not the only tools available. In this chapter I will show you through examples what else I used. While Ruby coding modifies the behaviour of Jekyll itself, the following techniques allow you to tailor the Jekyll theme you are using (in my case, Minimal Mistakes)

Replacing files

The most direct way to override some part of a Jekyll theme is by replacing some of its files directly. You do this by placing a file with the same name, under the same path as in the theme. Jekyll will use your file instead of the one defined in the theme. You do not need to change anything in the original theme. For example:

1. _includes/documents-collection.html: The difference between the two files:

-  {% include archive-single.html type=include.type %}
+  {% include {{ include.included_archive_layout | default: "archive-single" }}.html type=include.type %}

Remember, I did not edit Minimal Mistakes’ file, I just overrode it with mine. I added an optional parameter included_archive_layout to the include file, because from _layouts/updates.html I want to use a modified version of archive-single: archive-update, which also shows the associated categories under each post. This is important because my updates layout shows posts from every collection on the site.

2. _includes/footer.html: Modified the footer to

• include a download link of my CV
• instead of opening the atom feed (of the Post collection) directly. It opens a page with separate feeds for all my collections

One potential drawback of this technique is that if the original file in Minimal Mistakes is updated, your override won’t automatically reflect those changes, which might or might not be an issue, depending on your needs. You most likely won’t even notice, if you don’t check it yourself after a Minimal Mistakes update. This is not the case with the next technique:

Including files and extending them

Here, you don’t replace the original Minimal Mistakes (MM from now on — for Pete’s sake, I’ve typed it enough times!) files, but extend them through inclusion. It works best for layout files, and if the original layout gets updated in a newer MM version, your page will get the update automatically (which can be an advantage or disadvantage as well). An example of this is _layout/collection-extended.html which reuses MM’s collection layout, but adds a subtitle. For example, the main title is Bugs in the Soup and the subtitle is Programming:

---
layout: collection
---

{{ page.subtitle }}
{{ content }}

Here, content will be replaced by the original content generated by MM’s collection layout, preceded by the page’s subtitle.

_includes/head/custom.html

This is a special case of Replacing files, but it is a bit different. It deserves mentioning separately because this is by design in Minimal Mistakes. In the MM theme, _includes/head/custom.html is an existing, empty file, containing only a couple of comments, and it is actually included in MM’s default.html, which is the root file of the whole layout hierarchy. It includes custom.html in the <head> part:

  <head>
    {% include head.html %}
    {% include head/custom.html %}
  </head>

This means it will be included in every page on your site, and it provides extensibility. I used it to include my custom.css file and my favicon which Jekyll wouldn’t otherwise include during the build process:

<link rel="stylesheet" href="{{ '/assets/css/custom.css' | relative_url }}">
<link rel="shortcut icon" type="image/x-icon" href="{{ site.baseurl }}/assets/images/favicon.ico">

Similarly, there is a corresponding _includes/footer/custom.html file for the footer, which I didn’t use, but the possibility is there, should you need it.

Third party plugins

In this section, I will discuss third party plugins that I used to further enhance the functionality of my site.

jekyll-feed

Installed as a Ruby gem, it performs the generation of feeds based on your site content. It is supported by GitHub Pages (GHP), so you can use it even if you rely on GHP to build your site. After having struggled so much with the Posts vs. custom collections support by Jekyll (taxonomies and related posts), it was a pleasant surprise that jekyll-feed is pretty configurable (see more) and is happy to recognise other collections beyond the almighty Posts. All I had to do in my _config.yaml is:

plugins:
  - jekyll-feed
...
feed:
  collections:
    - updates
    - programming
    - cooking
    - portfolio

The generated feeds are then output to the _site/feed/{collection}.xml files.

jekyll-seo-tag

jekyll-seo-tag is also a low hanging fruit for a newly launched site. It is installed as a Ruby gem and is also supported by GHP. The configuration effort is minimal, and it adds meta tags to your site. All you need to do is

1. Install it as a Ruby gem.

group :jekyll_plugins do
...
  gem "jekyll-seo-tag", "~> 2.8.0"
...
end

2. Add it to your _config.yaml:

plugins:
...
  - jekyll-seo-tag

3. Include it in the aforementioned _includes/head/custom.html

<!-- start custom head snippets -->
...
{% seo %}
<!-- end custom head snippets -->

Disqus

Disqus is a comment provider which lets readers comment and discuss under posts. It is even more third party than the two Jekyll plugins above, I could even call it fourth party. Why did I choose it then among all the supported comment providers by MM? During my research, this is what I found:

1. giscus and utterances
   • Pros: they leverage GitHub’s infrastructure, which would make them well suited for my site, however…
   • Cons: they require a GitHub account for the reader to comment. Since my target audience does not only consist of developers, but also traders and hobby cooks, they were out of the equation.
2. Facebook:
   • Pros: big, battle tested, most people have FB accounts.
   • Cons: privacy concerns.
3. Disqus:
   • Pros: big, battle tested, widely used, lets people comment without registration.
   • Cons: privacy concerns, shows ads (unless paid subscription), limited styling options (although you can choose between dark and light themes, which was more than enough for me)
4. Staticman v2/v3, Discourse: Although there are some key differences, I will cover them together. Both of these are really cool!
   • Pros: Self hosted, open source, no privacy concerns
   • Cons: quite advanced setup in both cases.

Since my site is not that big, and I don’t expect it to be in the near future, I wanted to start with something easy to set up. This excluded Staticman and Discourse. With giscus and utterances also out of the equation, I chose Disqus as the lesser evil of the two remaining giants. I won’t go over the installation process of Disqus here. It was relatively straightforward. If you want me to cover it, feel free to leave a (Disqus) comment below. I will be happy to write it, and open a champagne for my first reader comment. :)

In the future, if my site were to see a serious discussion activity, I would definitely consider switching to Staticman or Discourse, but that’s for a later story.

Outroduction

That concludes Part 2. of the series. In the next post, the site will finally go live! I will share a useful checklist for pre- and post-publishing, based on my experiences, and we will conclude the series with my final thoughts.

Links

• Part 1: Setup and Design Decisions
• Part 3: Publishing Takeaways and Final Thoughts
• Portfolio entry
• GitHub repo

Sources

• GitHub Pages dependencies
• jekyll-feed plugin GitHub
• jekyll-seo-tag plugin GitHub
• Minimal Mistakes documentation and demo site

Introduction

This is Part 1 in a three-post series, where I sum up the journey of building my website. In this part, I will discuss why I chose this tech stack, the structural design choices I made, and we will face our first challenge early in the implementation process.

Selecting the tech stack

After doing a little research on the topic, it was quite an obvious choice:

Why GitHub?

• You can host your personal site on GitHub Pages for free and use your custom domain.
• As a software engineer, hosting it on GitHub felt like a natural fit.

Why Jekyll?

• GitHub Pages comes with Jekyll integration, which makes Jekyll the obvious choice.
• Jekyll is a static site generator which is “blog-aware” - well suited for portfolio pages and blogs. Exactly what I needed.

Why Ruby, Liquid, HTML, Markdown, JavaScript, CSS?

These are the technologies Jekyll uses to build and customise the websites, so they would be hard to avoid. :)

Why Minimal Mistakes?

There are several good Jekyll themes out there, but I chose Minimal Mistakes, because it seemed to be flexible, customisable and feature-rich. It is also minimalistic in both style and design, which gives you a lot of freedom. This freedom comes with some drawbacks however. For a non-technical person the wide range of customisation possibilities can be overwhelming, but I was up for the challenge, and luckily it comes with extensive documentation which helped a lot.

Design

In this section I will tell you why I went for this page structure and what implications it had.

Why sub-blogs?

I have come up with this idea of sub-blogs, because I want to post in quite different topics for quite different audiences (e.g.: programming and cooking), so keeping them separated is a good idea. I could have created standalone sites for each, but that wouldn’t scale very well. If I suddenly decided to post about egg shoeing, which is a completely different topic, I would have to set up another site. Also, I thought it would be a good idea to show my professional and personal interests in one place, so people - my future clients - can get a better, more holistic impression about me.

Complication with sub-blogs

It caught me by surprise, that Jekyll doesn’t support sub-blogs natively. There are collections, which are similar. You can define your collections like Programming, Cooking, Portfolio and Updates, but they don’t get out-of-the box support for related posts and taxonomies (i.e.: categories and tags). There is one prominent collection called Posts which get all the love, but the rest (custom collections that you make) are left out. If I had gone for a classic single-topic blog, it would have worked beautifully, but I wanted to build my own structure, and I omitted the Posts collection entirely. This is where things got interesting. I had to extend Jekyll’s default implementation to add support for my sub-blogs. I will discuss this journey, the obstacles faced and the solutions I came up with.

The implementation process

Since I wasn’t familiar with the Jekyll framework, I explored its capabilities and limitations along the way. The road was a bit bumpy, but it wasn’t too steep, and the process was quite enjoyable.

Getting started

1. Since I had no prior knowledge, I started following this video tutorial which proved to be very helpful. It walked me through all the necessary steps to get me going, even installing the prerequisites, like Ruby and Powershell 7. It was easy to follow, and quite soon, I had a basic “Hello Jekyll” site publicly available on the internet. I didn’t complete the tutorial however. I diverged when he installed the Hacker theme. Even though its name suggests it would be a good fit for a software engineer’s personal site, I found it quite ugly — so I started looking for alternatives.

2. Enter Minimal Mistakes. I chose this theme because of the reasons discussed in Why Minimal Mistakes. I installed it as a remote theme in my _config.yaml:

remote_theme: "mmistakes/minimal-mistakes@4.27.2"

A remote theme can be any Jekyll theme that is publicly hosted on GitHub. You only need to declare it in your config file, and the rest is taken care of by the jekyll-remote-theme plugin. No need to clone the Git repo or install the Ruby Gem of the theme.

I also cloned the Minimal Mistakes repository, and studied their live site which functions as documentation and demonstration at the same time. This way I could compare the code in the repo, and the output it produces. By doing so, I learned how Jekyll works. Layouts, pages, collections, includes and Liquid templates.

Categories and tags (aka taxonomies)

3. At this point I had figured out my site structure discussed in Why sub-blogs? and realised that Jekyll only supported tags and categories (taxonomies) for the built-in Posts collection, but not for the custom made ones. I wasn’t happy about it, so this was the first major extension that I decided to make. I wanted the taxonomies work across all my collections (sub-blogs).

module AllTaxonomiesPlugin
  class AllTaxonomiesGenerator < Jekyll::Generator
    safe true
    priority :low

    def generate(site)
      all_tags = Hash.new { |hash, key| hash[key] = [] }
      all_categories = Hash.new { |hash, key| hash[key] = [] }

      # Iterate through all collections (not just posts)
      site.collections.each_value do |collection|
        collection.docs.each do |doc|
          if doc.data['tags']
            doc.data['tags'].each do |tag|
              all_tags[tag] << doc
            end
          end

          if doc.data['categories']
            Array(doc.data['categories']).each do |category|
              all_categories[category] << doc
            end
          end
        end
      end
      # Make available to Liquid templates
      site.data['all_tags'] = all_tags
      site.data['all_categories'] = all_categories
    end
  end
end

Disclaimer: My experience with Ruby is very limited and I relied on AI to write this code

---
layout: archive
---

{{ content }}

{% include posts-taxonomy.html taxonomies=site.data.all_tags %}

_layouts/all-tags.html

---
layout: archive
---

{{ content }}

{% include posts-taxonomy.html taxonomies=site.data.all_categories %}

_layouts/all-categories.html

4. The next obstacle was that I just couldn’t make my AllTaxonomiesGenerator run. I added all possible debug printing and logging, but it did nothing. My kind and helpful AI assistant tried everything, but after a couple of wasted hours, I realised we were just going in circles. So I did a good ol’ Google search, and the first hit was this GitHub issue. And it says:

mojombo on May 11, 2011

We can’t run user plugins on GitHub Pages due to security restrictions. You are free to generate your site locally and push the resulting HTML to a Git repo, however.

Old post, but still stands. It would have taken me only 5 minutes to figure this out if I started with Google instead of AI. (Don’t get me wrong, AI is great. It has been an immense help during this project, but one should not rely on it blindly.)

So I had two options to choose from:

1. Build my site locally and push it to another Git branch to publish.
2. Use GitHub Actions.

I felt that 2. is a bit too advanced for my use case. It is more powerful, flexible and customisable, but for my case 1. is perfectly adequate.

So I did the following modifications to my GemFile (-: line removed, +: line added)

- gem "github-pages", "~> 232", group: :jekyll_plugins
group :jekyll_plugins do
  gem "jekyll-feed", "~> 0.12"
  gem "jekyll-include-cache"
+ gem "minimal-mistakes-jekyll"
end

And my _config.yaml:

- remote_theme: "mmistakes/minimal-mistakes@4.27.1"
+ theme: "minimal-mistakes-jekyll"

This way I removed GitHub Pages and Minimal Mistakes is no longer a remote theme, but installed as a gem. (Don’t forget to run bundle install to apply those changes.) Now, if I run bundle exec jekyll build or bundle exec jekyll serve, Jekyll will also run my plugins during build. The compiled site will be placed under the _site folder.

Outroduction

That concludes Part 1. of the series. In the next post we will continue with the implementation process. I will show how the amusingly named monkey patching helped me overcome another technical challenge, and we’ll explore how to customise a Jekyll theme to your liking.

Links

• Part 2: Custom Implementation and Plugins
• Part 3: Publishing Takeaways and Final Thoughts
• Portfolio entry
• GitHub repo

Sources

• Jekyll
• Liquid
• Minimal Mistakes
• Minimal Mistakes documentation and demo site
• Jekyll plugins

The problem

It has a drawback, however. Repositories can grow pretty huge over time. At my company, 250–300 GB repositories are not uncommon, and you have to sync them down to your workstation in order to carry out your development work. Syncing can take a whole day, depending on your internet connection. It also requires a lot of disk space.

And that’s only one workspace. We have several streams (similar to Git branches), and if you want to work on more than one, you have to have them mapped to different workspaces on your disk. Even more syncing, even more disk space.

The solution

There is a useful trick, however, that can help you save a lot of time and disk space. It is possible to retarget your workspace to another stream. Depending on the differences between the two streams, the synchronisation after the switch can be very fast, and you will have to keep only one workspace worth of data on your disk.

Steps

1. Go to Edit > Preferences > Streams tab and make sure that "Work in stream" menu behaviour is set to Choose at the time of action.

Figure 1: Work in stream menu behaviour setting

2. In the left panel, select the Workspace tree.

Figure 2: Workspace tree

In the top dropdown menu, select the workspace whose stream you want to change.

The line marked with 1 shows the name of your workspace: synapse_DESKTOP-BF6888H_9492 and in parentheses the stream it is currently tracking: Develop.

The line marked with 2 shows the folder on your disk associated with the workspace.

3. In the right panel, select the Streams tab:

Figure 3: Streams view

You will see a tree structure of the streams available in the right panel.

4. Browse to the stream you want to switch to. Right click it and hover Work in this Stream.

Figure 4: Switch stream

A submenu will open with two choices: Use different workspace and Reuse current workspace. We want to choose Reuse current workspace in this case. This is why we selected Choose at the time of action in the settings in step 1. If you cannot see Reuse current workspace, then go back to step 1 to enable it.

5. Click Yes in the pop-up window asking if you want to get the latest revision:

Figure 5: Get latest revision pop-up

Depending on the differences between your previous workspace (Develop) and the new stream (release), this operation can be quite fast—certainly faster than syncing down the whole stream from scratch—and you will use half the disk space (only one workspace instead of two). There are some caveats, however:

1. If the target stream is very different, Perforce might warn about conflicting files or deletions.
2. Your folder on your disk will still be called d:\dev\workspaces\gummy\develop, but it now tracks the release stream. In practice it should not cause any problems, but it’s worth remembering. (Maybe you can plan your naming better next time. 🙂)