Building a website using GitHub and Jekyll

For 2021 I decided it was time to start sharing some of my developer adventures. I want to do this with the hope that it helps someone and as a way to learn for myself, as writing makes you aware of the things you know and the things you don’t.

The first step for this was to actually have a site for it, and embarrassingly enough, my web skills are close to none. I’ll blame Wordpress.

For my site I knew that:

• I didn’t want to pay for hosting. Sorry, been there, done that.
• I wanted to own the source code and use a very simple stack. Sounds like a static website generator tool!

1. Tools

Hosting

GitHub Pages was a very easy choice. You can host and push your changes directly from a GitHub repository, something which I’m very familiar with. And it’s free!

Static Website Generator

After a quick Google search it seemed to be a dilemma between Jekyll and Hugo. While they both looked great, I decided to go with Jekyll simply because it appeared to glue very well with GitHub Pages, as suggested in their main site or in this official tutorial.

2. Building the site

First, let’s install Jekyll to get that out of our way. They’ve got a great tutorial on how to do it. Once you’re done, running jekyll serve will deploy the app to http://localhost:4000/

It was time to look for a Jekyll theme. I chose minimal mistakes by Michael Rose, because it looked great for personal sites/blogs and because its GitHub repository is super well maintaned. Big kudos to Michael!

Time to build my actual site in the next few steps:

1. Integrating minimal mistakes. There are a few ways to do it but since I didn’t have an existing website, I forked the whole project and deployed it locally.
2. I then went file by file to first, understand how the project is built, and second, to remove all the clutter that I’m not going to need.
3. Tweaking the site settings in _config.yml. Pick a skin theme (of course had to be dark) ✅, fill in my personal information ✅, choose a photo where I look like someone professional ✅, SEO and Analytics (if any) ✅, etc.
4. Modifying _data/navigation.yml to add the pages I want to have: blog, CV, Portfolio and About. And of course adding the content.

3. Deployment

The deployment part is actually very simple. You just need to host your source code into a GitHub repository named your-github-username.github.io and tell Jekyll to build your static site. For this, you can use this GitHub action:

name: Build and deploy Jekyll site to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  github-pages:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/cache@v2
        with:
          path: vendor/bundle
          key: $-gems-$
          restore-keys: |
            $-gems-
      - uses: helaili/[email protected]
        env:
          JEKYLL_PAT: $

There’s a small but: you’ll need to have your source code repo public in GitHub. For you to have it private, you can either pay for GitHub Pro or alternatively as a middle ground, you can do the following: have 2 repos, one private and one public. The private repo will have your source code and run the Jekyll action into a separate branch, and then we’ll have another GitHub action to move the generated code (aka our website) to the public repo. This is how it looks like:

name: Build and deploy Jekyll site to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  github-pages:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/cache@v2
        with:
          path: vendor/bundle
          key: $-gems-$
          restore-keys: |
            $-gems-
      - uses: helaili/[email protected]
        env:
          JEKYLL_PAT: $
        with:
          target_branch: 'temp-static-site'

      - uses: actions/checkout@v2
        with:
          persist-credentials: false
          ref: temp-static-site
          clean: false

      - name: Pushes to public repository
        uses: dmnemec/[email protected]
        env:
          API_TOKEN_GITHUB: $
        with:
            source_file: '*'
            destination_repo: 'your-repo'
            user_email: 'your-mail'
            user_name: 'your-github-username'

And ​🎉 Every commit into master will update our site!

4. Domain

Your site will be automatically hosted in your-github-username.github.io. You probably want to give it a more personal touch, and .dev domains sounds like a great domain for a developer’s site, right!?

There are many domain providers so I won’t get into that. To me they all seem to provide very similar functionality so I went with something familiar and cheap: Google Domains. The yearly price is £10 which sounds fair to me. I only hope Google don’t kill Google Domains and I gotta switch to a new one 🤭

There are many tutorials on how to connect your just bought domain into your github page, like this. Something to not forget, is to enforce https as it’s a requirement for dev domains.

Hope you enjoyed the article. For any questions, my Linkedin and Twitter accounts are the best place. Thanks for your time!

You might find interesting…

• Building a backend, an API and a web client using Ktor
• Architecting mobile apps with Kotlin Multiplatform