Graham Watts

(he/him) IT geek - DevOps Engineer - Rescue dog and cat dad - Sometime runner and cyclist.

Having softly launched this page on 1st January 2022 some of those I had sought early reviews from have already asked how I put this site together. While a lot of the information on this question is already available from a number of sources I didn’t find a single, concise, source bringing together the whole process, so it seems like a good subject to discuss.

Criteria

While getting started I considered the following criteria and reasoning:

  1. Cheap to host
  2. Easy to secure with https
  3. Use my existing domains
  4. Primary function as a blog
  5. Easy ongoing maintenance
  6. Good learning experience
  7. Use tools I’m already familiar with

I looked at but rejected a number of off the shelf sites, such as SquareSpace. I was hoping not to pay (call me cheap!); this choice does mean I am responsible for more maintenance than an off the shelf solution, you pay your money (or not) and take your choice I guess. My needs are relatively simple and a simple static site seemed to cover what I needed. I already had some domains registered and wanted to leave the registrations untouched. I knew I wanted to include a blog too.

I’m not a web developer by trade and my skills with HTML/CSS etc. are not strong, I didn’t want to have to focus on learning web dev. I am however very familiar with Markdown and use it a lot already. It seemed to cover everything I needed, if only there was a way to build a website that would ingest and publish markdown files.

Back to top

Chosen Solution

  • Azure Static Web Apps
    • I came across the Azure Static Web Apps which provides a Free Personal tier
    • This covers the cheap to host, it also includes free SSL certificates and custom domains (although not apex domains, e.g. grahamwatts.co.uk won’t work but www.grahamwatts.co.uk will)
    • This solution also tightly integrates with GitHub and can automatically create GitHub Actions to build and publish the site, including staging environments.
    • Using a new solution in Azure also seems like a good fit for a learning experience while also using my existing GitHub setup
  • Jekyll
    • Now that I had a hosting solution in mind I needed a static website generator that would leverage Markdown. Jekyll which has a specific selling point around use of Markdown
    • It’s free and open-source.
    • It provides either HTML or Markdown for content creation and includes themes.
      • I can learn a bit of HTML and CSS when I want/need to but stick to Markdown and YAML for the rest…perfect!
  • Minimal Mistakes
    • It won for me for 3 reasons
      1. A clean look
      2. Dark theme option
      3. Great documentation!
        • Seriously, Michael, the creator has gone to great lengths to document working with the theme
        • Good documentation is both a rarity and a vital tool
  • Markdown
    • OK, I’ve mentioned it a lot already. If you’re not familiar with what Markdown is check out the Codecademy: What is markdown article
    • Put simply; it’s a language for writing structured text. So, rather than using a tool like, say, Word and having it embed a bunch of proprietary metadata alongside your code to determine the format of the file, Markdown allows you to define the format inline with your text
      • e.g. writing **some text in bold** in a Markdown file will result in your text being rendered as bold text
  • GitHub
    • For anyone not familiar with any form of computer development this is where the code, geeky, what is this bit comes in. I won’t try and teach it here, there are plenty of good resources available and maybe I’ll come back to this specifically in another article.
    • In simple terms GitHub is a place to safely store, share and version control things you write. It’s typically used for software but could equally just hold documents you create (although there are probably better solutions for that specific use case)
    • Azure Static Web Apps are built around modern software development practices and so you need to have your code hosted, GitHub is the default choice and choosing it allows the solution itself to automate a lot for you. Unless you’re tied into another platform I’d recommend GitHub for this project.

Back to top

Process

A few disclaimer notes before I get started. I use Windows 11 as my workstation machine, however Jekyll can have some issues on Windows and so I actually developed my site in an Ubuntu 20.04 instance on Windows Subsystem for Linux (WSL).

I will skip over some steps like working with git and WSL as I can’t hope to do those fundamental skill subjects justice in this article. I’ll look to cover them in future posts and try to come back and link them here.

I also wanted to have some files in the repo but outside of my site source files so I created my site in a directory inside of my git repo rather than initializing the repo at the site level. If you want to do this simply create your repo directory first and initialize it, then follow the Jekyll steps for creating a site. It does mean that you may need to add the _site directory to your .gitignore file.

Back to top

Prerequisites

Back to top

Getting started

  1. Create a working directory
    • e.g. C:\Users\<username>\Development or ~\Development
  2. Start with the Jekyll Step-by-Step Tutorial
    • This page even covers initializing a git repo in your site directory
    • Below is a view of my working directory where the src directory is the root directory referred to in the Jekyll tutorial
    • Much of this structure you will build out as you work through the tutorial and build you site, so don’t worry if this looks like more than you have at this early stage. I include this as an example for what you’re working towards. - Make sure that you add jekyll to your ruby gemfile
     source "https://rubygems.org"

 # Core site
 gem "jekyll"

     📦GrahamWattsWeb
   ┣ 📂src
   ┃ ┣ 📂_data
   ┃ ┃ ┣ 📜authors.yml
   ┃ ┃ ┣ 📜navigation.yml
   ┃ ┃ ┗ 📜ui-text.yml
   ┃ ┣ 📂_drafts
   ┃ ┃ ┗ 📜2022-01-03-how-i-built-this-site.md
   ┃ ┣ 📂_pages
   ┃ ┃ ┣ 📜about.md
   ┃ ┃ ┣ 📜blog.md
   ┃ ┣ 📂_posts
   ┃ ┃ ┗ 📂general
   ┃ ┃ ┃ ┣ 📜2021-12-31-first-post.md
   ┃ ┃ ┃ ┗ 📜2022-01-01-why-knowledge.md
   ┃ ┣ 📂assets
   ┃ ┃ ┣ 📂images
   ┃ ┃ ┃ ┣ 📂blog
   ┃ ┃ ┃ ┃ ┣ 📜blog-teaser.webp
   ┃ ┃ ┃ ┗ 📂core
   ┃ ┃ ┃ ┃ ┣ 📜bio-photo.webp
   ┃ ┣ 📜404.md
   ┃ ┗ 📜index.html
   ┣ 📜.gitignore
   ┣ 📜Gemfile
   ┣ 📜Gemfile.lock
   ┣ 📜_config.yml
   ┣ 📜readme.md
  3. If you haven’t already initialized your repo, do so now
    • e.g. git init
  4. If you haven’t already created your remote repository on GitHub, do so now and push your repo to GitHub
  5. You’re now ready to begin building your site!

Back to top

Theme

  • If you’re using Minimal Mistakes add a ruby gem to your Gemfile
    • e.g. gem 'minimal-mistakes-jekyll'
    • Other themes are available; see Jekyll: Themes for more information
source "https://rubygems.org"

# Core site
gem "jekyll"

# theme
gem "minimal-mistakes-jekyll"

Back to top

Ruby Gems

  • Ruby supports add-on features, or plugins, which are referred to as gems
  • Gems are declared in the Gemfile and are installed using bundle install or updated using bundle update
  • Gems are processed in the order they are declared in the gemfile
    • So if you have plugins that require other plugins, you’ll need to declare them in the order you want them to be installed and processed
    • For example if you’re using jekyll-redirect-from to add optional redirection URLs, and you want to use jekyll-sitemap to generate a sitemap, then you’ll need to declare jekyll-redirect-from before jekyll-sitemap

Example Jekyll Gemfile

source "https://rubygems.org"

# Core site
gem "jekyll"

# theme
gem "minimal-mistakes-jekyll"

# plugins
group :jekyll_plugins do
    gem "jekyll-gist"
    gem "jekyll-feed"
    gem "jekyll-paginate"
    gem "jekyll-include-cache"
    gem "jekyll-coffeescript"
    gem "jekyll-archives"
    gem "jekyll-redirect-from"
    gem "jekyll-sitemap"
end

Back to top

Testing

  • In a terminal, navigate to the root of your site
    • e.g. cd C:\Users\<username>\Development\<your-site-name>
  • Run the command bundle exec jekyll serve
  • Your site is now running on port 4000 and will be available at (http://localhost:4000/)
    • This also applies when using WSL
  • In general, the site will hot reload as you add and edit pages.
    • The main exception to this is changes to the _config.yml file.
    • If you make changes to the _config.yml file, you’ll need to restart the server.
    • Ctrl + C to stop the server
    • bundle exec jekyll serve to restart the server
  • As you build out your site and start working with posts you may want to either include draft posts or future dated posts
    • Draft posts are not visible on the site until they are published
      • To include draft posts run bundle exec jekyll serve --drafts
    • Future dated posts are not published until their date has been reached
      • To include future dated posts run bundle exec jekyll serve --future
    • You can combine command switches
      • e.g. bundle exec jekyll serve --drafts --future

Back to top

Configuration

_config.yml

  • Configuration for Jekyll is done in the _config.yml file.
  • You can find a sample _config.yml here
  • Core site information such as title and URL go in this file
  • Add as much default configuration as possible to this file
    • If you’re a single author site add your profile details and social links here
    • Define default layouts and page configuration such as allowing sharing or showing the date

Back to top

Front Matter

  • Front matter is a feature of a technology called Liquid which is used by Jekyll
    • Liquid consumes header information, Front Matter, and uses it to render the page content in formatted HTML output
  • Include the following at the top of your pages
---
---
  • Between these two --- lines you can define any metadata you want in YAML format

e.g.

---
author: {{ site.author }} # Or other author as listed in /_data/authors.yml
title: "Title" # Optional if the page name is not ideal
excerpt: "Brief synopsis of the page" # Optional
---

Back to top

Variables

  • Variables are called using the {{ and }} characters
    • e.g. “{{ site.author }}”
  • Many items can be variables sourced from either _config.yml such as site.author or default values provided by Jekyll
    • e.g. author: {{ site.author }}
    • e.g. title: "{{ page.title }}"
    • e.g. excerpt: "{{ page.excerpt }}"
  • Variables can also be used in page content
  • Queries based on variables can also be written
---
layout: posts
permalink: /blog/
title: "Blog"
entries_layout: grid
---
# Latest Posts

{% for post in site.posts %}
- ## [ {{ post.title }} ]({{ post.url }})
      {{ post.excerpt }}
{% endfor %}

Back to top

Pages and Navigation

  • Pages can go in the site root directory, or as I prefer in a _pages directory
  • For static pages I recommend using Permalinks
    • e.g. /about/
  • You can write in Markdown or HTML
    • But let’s be honest if you’re using HTML you probably don’t need to be using Jekyll 😜
  • See Jekyll: Pages for more information

Back to top

Posts

  • Posts go into the _posts directory under your site root
  • Posts should have the naming convention YYYY-MM-DD-title-of-post.md for Jekyll to process them
    • This also allows Jekyll to assign a publish date and provide a title for the article - although you can override these using Front Matter if you wish
  • As with Pages posts can be written in Markdown or HTML
  • See Jekyll: Posts for more information

Back to top

Deployment

I’m not going to spend a lot of time here; the folks at Microsoft already have an excellent article on deploying Jekyll to Azure Static Web Apps using GitHub.

Check it out here: (https://docs.microsoft.com/en-us/azure/static-web-apps/publish-jekyll)

Top Tip: remember to push your changes to GitHub before deploying to Azure

Back to top

Summary

As with everything there is more to it; however I hope this gets you started and saves you the time and searching I went through while researching making this site. I’ve tried to link to resources inline as much as possible and below are some of the key resources that got me through this.

In particular checkout Scott Hanselman and his YouTube channel. He covers loads of great topics and his video on Azure Static Web Apps got me started on this track.

If this article helped inspire you please consider sharing this article with your friends and colleagues, or let me know via LinkedIn or X / Twitter. If you have any ideas for further content you might like to see please let me know too.

Back to top

Resources

Back to top

Updated:

You May Also Enjoy

Troubleshooting Skills

25 minute read

Looking at the art, and the science, of troubleshooting technical issues