Writing blogs using GitHub pages

GitHub-pages is a way of hosting Jekyll based static sites. I decided to use it to host my tech blog. After all we are all living in the age of everything as code.

So why not blog as code.

This post is a TL;DR and a compilation of sources for more details.

Specification for a blog solution

  1. Should have ability to run locally and test before publishing (offline support)
  2. Version control
  3. Use markdown as the formatter for writing
  4. Have good templating support

Solution 1 - Self Hosting

Jekyll is site generator where you can write content for your site using markdown format. There are many themes available as well, to bootstrap your site code. I used to host my blog by running jekyll server on Amazon EC2 instance and using AWS Route 53 Authoritative DNS server to route traffic to the public IP of my EC2 instance. To enable TLS I used Let’s Encrypt to get a server certificate which is valid for 3 months. And use the certbot to renew my server certificate automatically.

That’s a lot of work, also recurring cost for AWS infrastructure.

Solution 2 - Using GitHub Pages

You have to create a new github repository with name .github.io.

For an example, my GitHub username is busy-spin. And the repository I use to host my blog is busy-spin.github.io. Publishing content to your website is as simple as pushing content to GitHub repository.

I can run the blog site locally as both approaches use Jekyll site generator.

Testing Site Locally

Bellow is a complete guide on how to test your site before publishing.

Guide - Testing your side locally with Jekyll

Important commands are

To install the required Ruby packages

bundle install

To run the jekyll server locally

bundle exec jekyll serve

Jekyll process has a file watcher so once you update the content it will auto compile it to html code.

Extras

Adding mermaid flow chart support for GitHub pages.

mermaid.js chart support is available by default in GitHub wiki, GitHub projects. But enabling mermaid.js for GitHub pages is not supported out of box and also not trivial to enable. I found this neat trick from fellow GitHub blogger jackgrubber - Embed-Mermaid-in-Jekyll-without-plugin.

```mermaid
flowchart TD
    A[Learn difficult concepts] -->|Create Experiment| B{Experiment}
    B --> | Too hard to understand | C[Read more and write about it]
    B --> | Got a good grip of concept | D[Write about it]
    C --> | Experiment Again | B
    D --> | Level up again | A
```  

flowchart TD
    A[Learn difficult concepts] -->|Create Experiment| B{Experiment}
    B --> | Too hard to understand | C[Read more and write about it]
    B --> | Got a good grip of concept | D[Write about it]
    C --> | Experiment Again | B
    D --> | Level up again | A

Other Helpful References

Jekyll Quick Start

GitHub Pages - Quick Start

Writing on GitHub - A complete guide on markdown

GitHub - Basic Writing And Formatting Syntax


13 May 2024 - Isuru