This post will walk through the steps necessary to build a blog using GitHub Pages and Jekyll on Windows.

Environment set up

Checkout the Windows Development Environment post for a guide on setting up a Windows development environment. The section below covers only the items necessary for this tutorial.

  1. Install Scoop. Scoop is a command-line installer for Windows

    1. Open PowerShell.

    2. Set the execution policy.
      > set-executionpolicy remotesigned -s currentuser
    3. Install scoop.
      > iex (new-object net.webclient).downloadstring('')
    4. Add extras and versions buckets.
      > scoop bucket add extras
      > scoop bucket add versions
  2. Install Git. Git is a version-control system for tracking changes in computer files.

    > scoop install git
  3. Install Ruby. Ruby is a dynamic, open source programming language with a focus on simplicity and productivity.

    > scoop install ruby
  4. Install MSYS2. MSYS2 is a software distro and building platform for Windows.

    > scoop install msys2
    > msys2

    A console will open. Once it finishes running commands just close the console.

  5. Install the MSYS2 and MINGW development toolchain.

    > ridk install 3
  6. Install Jekyll

    > gem install bundler jekyll

Create your site repository

  1. Create a new repository for your site.
    > jekyll new my-site

    This bootstraps a new Jekyll site in the directory my-site.

  2. Initialize Git.
    > cd my-site
    > git init
  3. Create a new empty repository on GitHub. Navigate to{username}?tab=repositories and click the ‘New’ button. create-new-repository

  4. Copy the repository link. clone-repository

  5. Add the repository link as a remote.
    > git remote add origin {copied repo url}
  6. Add files to track.
    > git add .
  7. Commit changes.
    > git commit -m 'initial commit'
  8. Push to GitHub.
    > git push origin master

Host your site on GitHub pages

GitHub Pages allows you to host your web site for free from a GitHub repository.

  1. Update the Gemfile to enable GitHub pages. You need to comment out gem "jekyll" and then uncomment the gem "github-pages". The result should look like below.
    # This will help ensure the proper Jekyll version is running.
    # Happy Jekylling!
    # gem "jekyll", "~> 3.8.4"
    # This is the default theme for new Jekyll sites. You may change this to anything you like.
    gem "minima", "~> 2.0"
    # If you want to use GitHub Pages, remove the "gem "jekyll"" above and
    # uncomment the line below. To upgrade, run `bundle update github-pages`.
    gem "github-pages", group: :jekyll_plugins
  2. Push your changes to GitHub.
    > git add Gemfile
    > git commit -m "update Gemfile"
    > git push origin master
  3. Go to the Settings tab for your repository. github-select-page-rule

  4. Scroll down to the GitHub Pages section and set the source to the master branch. github-pages

  5. Navigate to {your username}{your repository} and verify your site is working.

Using a custom domain name

  1. Purchase a domain name. I recommend Namecheap but you can use plenty of other domain name registrars. I bought for ~$30 and it renews at ~$20 a year.

  2. Create a free Cloudflare account. Cloudflare is used as the DNS provider so you can route traffic to your site securely using SSL.

  3. Add a site to your Cloudflare account. cloudflare-add-site

  4. Get the Cloudflare nameservers for your site. cloudflare-nameservers

  5. Add the Cloudflare nameservers to Namecheap (or whatever registrar you use). namecheap-custom-dns

  6. Add CNAME records to Cloudflare. You will add one apex record ( in my case) and another wwww record ( in my case). Both of the values will be {username} So for my site, the value is cloudflare-cname

  7. Add a CNAME file in your repository. This is used to register the domain name with GitHub pages and point to the correct repository.
    > cd my-site
    > echo "{your domain}.com" > CNAME
    > git add CNAME
    > git commit -m 'added CNAME'
  8. Open the Page Rules dashboard and select ‘Create Page Rule’. cloudflare-select-page-rule

  9. Add Page Rule to always use HTTPS. cloudflare-page-rule-https

  10. Add Page Rule to forward to the apex. cloudflare-page-rule-forward-to-apex

Now your site is set up to use your custom domain name and you will get a better SEO ranking with Google since you are using HTTPS :tada:.

Create a post

To create a post, we need to add a new markdown file into the _posts directory. Each post is a standard Markdown file which uses the kramdown syntax. Each post should have a ‘Front Matter’ section at the top which contains the Jekyll options formatted in YAML. Below is the ‘Front Matter’ for this post.

layout: post
title:  How to Jekyll
permalink: how-to-jekyll
date:   2018-10-27 11:37:39 -0400
  - jekyll
  - windows
  - blog
  - markdown
comments: true

Learn more about ‘Front Matter’ on the Jekyll website.

Check out this tutorial to find out more about adding Disqus to your blog.

Then the rest of the file is your blog post content.

Check your site

Before pushing your changes to GitHub, you should check your site locally. Run the Jekyll site locally using the following command from the root of your repository.

> bundle exec jekyll serve

Then navigate to your site at http://localhost:4000.

Deploy your site

Once the site looks good, then we can deploy our site by pushing the latest changes to GitHub.

> git push origin master 

Then navigate to your custom domain name and check that it was deployed successfully.


In this post we covered:

All the code for this site is located on my GitHub repo if you want to see more details. Let me know if you have any questions or find any issues in the comments below. Thanks! :smile:

Additional Resources