• Set up a GitHub Pages repository
  • Set up a Jekyll and Jekyll project
  • Choose and setup a themes
  • Configure custom domain
  • Add DISQUS comments
  • Add Google Analytics
  • Future steps

Prerequisites: GitHub account and Git client of your choice (instructions use command line git)

Set up a GutHub Pages repository

Go to https://pages.github.com/ and follow the guide for user/organization site or project site. I choose a user site. Assuming git-username is your git username, create a new repository called git-username.github.io in your GitHub account. If you have a payed account, you can choose a Private repo. I’m going to use a command line Git client in bash shell:

mkdir ~/work
cd ~/work
#the following line might differ based on your git setup preference
git clone git@github.com:git-username/git-username.github.io.git
cd git-username.github.io/
echo "hello from GitHub Pages" > index.html
git add .
git commit -m "added index.html"
git push
open https://git-username.github.io

At this point GitHub Pages is serving your static website from the master branch of your repository. If you’d like to evolve your website as static HTML site, this might be all that you need. You can also go to Configure DNS section if you want to serve your site under your custom domain.

If you choose to write your pages/posts in markdown and have GitHub Pages generate a website continue reading on setting up Jekyll.

Set up a Jekyll and Jekyll project

I choose to use Jekyll to handle my GitHub Pages website. This is for several reasons:

  • I will write my posts in plain markdown and Jekyll will generate the website pages for me following a theme chosen by me
  • GitHub Pages supports Jekyll internally, so that I push my *.md files only and it will be pure GitHub Pages generating website for me
  • Jekyll/GitHub Pages support themes to choose from; internal and 3rd party
  • Jekyll has a lot plugins; GitHub Pages supports only limited set of plugins for security reasons, but it does have support for DISQUS

So roughly following this guide: https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/

ruby --version
#should be 2.1.0 or higher, if not "brew install ruby" or https://www.ruby-lang.org/en/downloads/
gem install bundler
#in the root directory of your local Jekyll site repository
echo "source 'https://rubygems.org'" > Gemfile
echo "gem 'github-pages', group: :jekyll_plugins" >> Gemfile
bundle install
#preserve GitHub Pages version of `Gemfile`, delete `index.html` example from section 1
cp Gemfile Gemfile.githubpages
rm index.html
bundle exec jekyll _3.3.0_ new . --force
cp Gemfile Gemfile.jekyll
mv Gemfile.githubpages Gemfile
bundle exec jekyll serve

The last command will generate and start Jekyll site locally on port 4000. Open http://localhost:4000/ to see the your site locally before you push it to the GitHub repo and therefore publish it.

Notice one post Welcome to Jekyll! that was generated by default.

While Jekyll is running locally you can make changes to your site and it will pick them up as soon as you save the file.

Note that the Welcome to Jekyll! auto-generated post contains date: 2018-03-19 18:17:35 -0400 at the top of the markdown separated by ---. Avoid having time set there! The links to the posts contain dates. Depending on when the site is generated from markdown, the link can be /2018/03/19/welcome-to-jekyll.html or /2018/03/20/welcome-to-jekyll.html. Set the date to date only, like 2018-03-19 without time and zone. Or even better remove it from your post header and and let the date of the post be deduced from the filename 2018-02-19-my-first-post.md. It’s a good idea to name you post files according to this default best practice anyways as it helps in sorting and organizing.

Global site configuration

In the root directory of you Jekyll site there’s a _config.yml file that contains site-wide configuration, like title, owner’s email. It can also contain settings used by your theme or even custom variable that can be referred in the templates.

You definitely want to set your site’s title and description used by all themes, your email, and the url which you must set if you want to use DISQUS comments.

title: Your awesome title
email: your-email@example.com
description: Write an awesome description for your new site here. You can edit this line in _config.yml. It will appear in your document head meta (for Google search results) and in your feed.xml site description.
baseurl: "" # the subpath of your site, e.g. /blog
url: "https://git-username.github.io" # or your custom domain, e.g. http://your-name.com
twitter_username: jekyllrb
github_username:  jekyll

Add a post in markdown

Make sure that you are in the root directory of your local Jekyll site repository and create a post as an .md file using the following command or your favorite text editor:

#in the root directory of your local Jekyll site
cat <<EOT >> _posts/2018-02-19-my-first-post.md
---
layout: post
title:  "My first post"
---
# My first awesome post
How cool is that?
- Use [Markdown!](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
  - *Easy to create* as plain text
  - And **beautiful** when rendered as website
- [Here's how we did it](http://www.novytskyy.com/2018/02/19/setting-up-a-blog-with-github-pages-and-jekyll.html "Setting up a blog with GitHub Pages and Jekyll")
EOT

Don’t forget to push your changes to GitHub

Choose a themes

GitHub Pages supports official and third-party themes. They are applied in slightly different way.

Apply and configure a theme

So I’ve chosen the So Simple theme. Modify _config.yml in the root of you GitHub Pages Jekyll site to contain:

remote_theme: "mmistakes/so-simple-theme"
author:
  name: Your Name
  twitter: twitter-username
  picture: /images/author.jpg

Put your author picture in ./images/author.jpg relative to the root folder, So Simple theme will style it in a nice circle.

Additional setup for the so-simple-theme can be found at https://github.com/mmistakes/so-simple-theme

Configure custom domain

You will need your domain name registered and have access to DNS configuration for it. Let’s assume your custom domain is your-name.com and your GitHub Pages domain is git-username.github.io (the one that you get anyways with GitHub Pages).

Go to your registrar’s DNS configuration for your-name.com to do the following:

  • add a record with type ALIAS or ANAME and git-username.github.io as the value
  • add a record with type CNAME, www subdomain and git-username.github.io as the value

Add a file name CNAME in the root of your site with your custom domain:

echo 'www.your-name.com' > CNAME

Git add / commit / push.

DNS changes may take time to propagate

Add DISQUS comments

Create a DISQUS account and set up your site in Disqus. In your site configuration in Disqus you are going to choose your website name that is going to be your shortname. Also you need to enter your Website URL that must match the domain name that you’ve chosen to serve your domain under. Otherwise Disqus will not initialize the comment section for security reasons.

Following current example I’m editing _config.yml file in the root directory of your Jekyll site to contain and using disqus-username as my disqus.shortname and https://git-username.github.io as my url that matches Website URL configured in Disqus and the domain under which the site will available:

url: "https://git-username.github.io"
disqus:
  shortname: disqus-username

Add Google Analytics

If you are using mmistakes/so-simple-theme theme, as I am, provides support for Google Analytics out of the box. Just add the following to your _config.yml

google_analytics: UA-XXXXXXXX-X

Future steps

  • tags/labels on posts and listing
  • investigate content section generated by headers
  • customizing theme/css
  • add LinkIn, Twitter, other buttons to follow an author and to share a post

Happy and easy blogging!