ADR is for architecture what Git’s commit log is for code. It is a light-weight, append-only, process for documenting changes to a system.

Below is an example of an ADR. It also serves as the ADR for this site.

If you are creating an ADR for your team or organisation, you can take a more structured approach, like this one by Micheal Nygard.

24-10-2022 - Init

Set up GitHub Pages with Jekyll following this guide.

30-10-2022 - Integrated Google Analytics

Added the script GA provided in _includes/ and the ID in _config.yml.

Subsequently removed the GA script from _includes/. Minima, the theme being used, just required GA ID to be added in _config.yml.

31-10-2022 - Integrated Disqus

Disqus supports both reactions and comments. Minima has first class support for it. Just need to add a Disqus ID to _config.yml.

31-10-2022 - Removed Disqus

Disqus doesn’t fit well with the theme. Removed it and looking for an alternative.

31-10-2022 - Integrated Giscus

It’s built using GitHub Discussions, requires a GitHub repo to work, which I have. Minima doesn’t support it though out of the box, so have to start looking under the hood now.

RISK: Seems the post layout isn’t extensible, which is where I want to add the comments box. The workaround is to copy _layouts/post.html from the Minima theme into my repo and make changes into that file. It’s not pretty, and it is a risk that might break future upgrades to the theme :(

31-10-2022 - Integrated Applause

Applause is a simple, no config library that will allow readers to like posts.

  • Upgraded Minima from v2.5 to v3.0 because the older version doesn’t support _includes/custom-head.html which is where I need to add the include scripts for Applause.
  • v3.0 is not available as a Gem, so pulling theme from GitHub now. _config.yml says remote_theme: jekyll/minima now instead of theme: minima.

31-10-2022 - Custom CSS

Added custom CSS for the applause button to center it and add top/bottom margins. The css is added to assets/css/style.scss.

06-12-2022 - Recent posts

Added recent posts in post.html to increase readership.

22-12-2022 - Show tags on homepage

Copied _layouts/home.html into local repo to be able to customize it. Tags are displayed against each post preview.

23-12-2022 - See posts by tag

Followed a blog to show posts by tag under the URL /tag/{tag}. A python script tag-pages-generator.py generates a page for each tag since Jekyll I assume is rendered server side. The script needs to be added as part of pipeline otherwise I would manually have to run it whenever a tag is added or updated.

26-12-2022 - Automated /tag/{tag} pages generation with GitHub Actions

This site was previously set to deploy from Deploy from a branch which automatically generates a GitHub Actions workflow. That workflow cannot be edited.

To add custom build steps, the deployment setting (Settings > Pages > Build and deployment > Source) is now set to GitHub Actions (beta). A workflow is generated under .github/workflows/jekyll-gh-pages.yml. It is customized to generate tag pages dynamically.

12-06-2023 - Locked Minima theme to a specific git commit

No stylesheet was loaded as I published a new post today. I am using an unreleased version (3) of Minima by loading source from GitHub. Looking at issues reported on GitHub, it seems the main branch can contain breaking changes. Found this suggestion to lock on to a specific commit and get back to previous working state.