This is yet another tutorial of how to setup a jekyll blog within github.

install required software

setup blog

  1. Create a new repository
    • Initialize with README to allow immediate cloning
    • If you don’t have a github account, signup
    • If you want to add a blog to an existing repository, ignore this step
  2. Setup gh-pages branch
    • Create a new branch gh-pages
    • If the repository purpose is to host the blog only, you may go to repository settings (https://github.com/<username>/<repo>/settings) and set Default branch to gh-pages
  3. Checkout branch and create Jekyll blog
    • Checkout gh-pages branch git clone https://github.com/<username>/<repo>.git --branch gh-pages --single-branch <folder>
    • cd <folder>
    • jekyll new --force .
  4. Configure Jekyll
    • edit _config.yml
    • baseurl: /<repo>
  5. Stage, Commit and Push
    • git add .
    • git commit -m "first commit"
    • git push
  6. Go to http://<username>.github.io/<repo>/ and enjoy!

more configurations

edit _config.yml

# Site settings
title: Your awesome title
email: your-email@domain.com
description: > # this means to ignore newlines until "baseurl:"
  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: "/<repo>" # the subpath of your site, e.g. /blog/
url: "http://<username>.github.io/<repo>/" # the base hostname & protocol for your site
github_username:  <username>

# Build settings
highlighter: pygments
markdown: redcarpet
# extensions reference: https://github.com/vmg/redcarpet
redcarpet:
  extensions: ["fenced_code_blocks"]

add a theme

Some jekyll themes can be found here:

  • http://jekyllthemes.org/
  • http://qrohlf.com/posts/5-best-jekyll-designs/
  • https://mademistakes.com/work/jekyll-themes/
  • https://www.google.com/?q=jekyll+themes

gitignore

You may want to ensure your .gitignore has the following:

_drafts
_site
.sass-cache

references

  • https://help.github.com/articles/using-jekyll-with-pages
  • https://help.github.com/articles/repository-metadata-on-github-pages/
  • http://24ways.org/2013/get-started-with-github-pages/
  • http://www.smashingmagazine.com/2014/08/01/build-blog-jekyll-github-pages/