Setup Github pages with Jekyll

because they are awesome

Posted by Multiplatform App on August 22, 2021 · 3 mins read

(Updated 2021-09-04)


Setting up blog using Github pages and Jekyll


  • Pick a Jekyll theme from :
  • Fork the repo:
  • Change the name of the forked repo to
  • Pull repo down to run locally (ref:
    • Install Jekyll on local machine: gem install jekyll bundler
    • From the cloned github repo, run: bundle install to restore project
    • Start jekyll server: bundle exec jekyll serve
  • Clean up:
    • Update _config.yml file with your details and delete unrelated content.
    • Delete all default post from _posts. folder.

Write Post

  • From _posts/ folder, add mardown file following year/month/date/post-title convention
  • Add the following details to top of the markdown file:
    layout: post
    title: "Setup Github pages with Jekyll"
    subtitle: "because they are awesome"
    date: '2021-08-22 17:06:15'
    background: '/img/bg-about.jpg'

Custom syntax highlighting with css file.

Make sure kramdown and rouge are installed

gem install kramdown rouge

Add these to _config.yml file

markdown: kramdown
highlighter: rouge

Download a css stylesheet that you like.

I’m using monokai.css

Add monokai.css file to assets folder (the assets folder on same level woth _posts folder)

Run this command to copy monokai.css to _site\assets\ folder

rougify style monokai > assets/monokai.css

Open head.html and add link to monokai.css right below main.css

<link rel="stylesheet" href="/assets/main.css">
<link rel="stylesheet" href="/assets/monokai.css">

Fix code highlighting indentation

Code indentation might be display as 8 spaces. Example:


To fix this, use VSCode and Convert Indentation to Spaces



Reference Images in Markdown Compliant manner

To achieve this install jekyll-postfiles. Add this to Gemfile, then run bundle install

group :jekyll_plugins do
  gem 'jekyll-postfiles'

And that’s it, images in same folder as Markdown files under _posts folder will automatically be copied to _site/yourpost folder