Setup Github pages with Jekyll

(Updated 2021-09-04)

Background

Setting up blog using Github pages and Jekyll

Installation:

• Pick a Jekyll theme from : https://jekyllthemes.io/
• Fork the repo: https://github.com/StartBootstrap/startbootstrap-clean-blog
• Change the name of the forked repo to yourgithubhandle.github.io
• Pull repo down to run locally (ref: https://jekyllrb.com/)
  • 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'
end

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