How to Setup Jekyll on Github Pages

Forward

Tumblr, while an excellent platform for reliability and simplicity, has weak support for incorporating any sort of code in your posts. This piece is about why I have settled on Jekyll + Github Pages, how to implement it yourself, and some things to note.

Jekyll converts markdown into HTML. Github pages allows you to host Jekyll (and other static websites) for free.

Jekyll is good idea because:

  1. Syntax highlighting is baked in.
  2. Including HTML or JS in posts is easy. Check out D3.js - Data-Driven Documents to see what you can do with just that library.
  3. It’s far more portable than Tumblr and many other CMS type solutions – if I ever wanted to migrate into another solution later.
  4. Github Pages is free, fast, and reliable.
  5. Writing with Github’s Atom is pretty great:
    1. Not internet dependent
    2. Decent Integration with both Github and Jekyll.
    3. Lots of themes, here’s a screenshot of my workspace: live preview markdown github atom
    4. I do personally prefer Bear Writer but the integration with Jekyll is non-existent, so I’ll either be migrating those drafts over or building a script that’ll integrate the two in the future.

Jekyll is bad because:

  1. It’s awkwardly opinionated with some things:
    1. A Post’s filename must be YYYY-MM-DD-SomeBlogPost.md rather than pulling a post’s date from a file’s metadata.
    2. Posts and their respective files, like any embeded images, are not contained together. This reduces portability, transparency, and referencing these things is a bit annoying when doing by hand.
    3. Themes are encouraged to be installed like any other ‘gem’, which creates 2 problems:
      1. Theme customization is awkward and non-trivial
      2. Transparency: The “where is my toothbrush and am I expected to resort to Google to find it?” sense, not the “it feels magic” sense.
  2. And not opinionated on others:
    1. Theme organization is up to the designer. Do make sure you have your Find function hot keyed.
    2. All images embed horizontal images regardless if they’ve been taken them vertically.
      • TODO: Build a plugin for this.

It’s worth checking what the other issues are before going down this path for yourself as well.

Why not Wordpress, Rails, or some CMS solution?

My writing is not data so it doesn’t need a database.

Most interactions on this site would probably like this: Person « (talks to) » Webpage.

Adding a database would make every site visit look like this:

  1. Person « (talks to) » Webpage « (talks to) » Database
  2. This could happen as well and can quickly become a non-obvious security issue:

    Person: Give me this content.

    Website: Hold while I ask my database to find that for you. Hey Database, give me this content.

    Database: OK

    Person: Thanks Website! Hey Database?

    Database: Hello.

    Person: Delete all of your data.

    Database: OK.

  3. To speed things up, you would have to build even more stuff on top of it:
    1. Person « » Webpage « » Faster $$$ Database « » Slower $ Database
    2. Person « » Webpage « » load balancer « » Database

Non exhaustive list of drawbacks would include:

  1. Another point of failure
  2. Added cost
  3. Added complexity (implementation, security, you name it)
  4. Not transparent
  5. Not portable
  6. Slower because visitors must wait for the website to wait for the database before getting content.

Setup (and forget what’s on Github or Jekyll, they are not super helpful):

Requirements:

  • GNU/Linux, Unix, or macOS
  • Ruby version 2.1 or above, including all development headers
  • RubyGems
  • GCC and Make (in case your system doesn’t have them installed, which you can check by running gcc -v and make -v in your system’s command line interface)
  • Jekyll and Bundler installed. Run this if you’re unsure: gem install jekyll bundler

Steps:

  1. Head over to GitHub and create a new repository named username.github.io, where username is your username (or organization name) on GitHub.
  2. Clone the repo git clone https://github.com/username/username.github.io
  3. Choose a Jekyll Theme that you like, download that theme’s repo and extract the files in your username.github.io folder that you’ve just cloned.
  4. Depending if you deal with a User/Organization (UO) site or a Project site (P), do via Stack:
    1. In _config.yml, set the baseurl parameter to baseurl: '' (UO) or baseurl: '/repositoryName' (P). This may change when you add a custom domain.
    2. In .gitignore add _site to a newline.
    3. Then run in the root folder: ``` sh $ git rm -r –cached _site $ cd _site $ touch .nojekyll #this file tells gh-pages that there is no need to build the site.
  5. Edit the Gemfile to make sure it includes the gem 'github-pages' line that’s uncommented somewhere. Then test if the template works locally: bundle exec jekyll serve
  6. Add, commit and push to master. git add .; git commit -m "init theme"; git push
  7. Navigate to https://username.github.io and it should be live with bells, whistles and all.

Notable Alterantives:

  1. Hexo: NodeJS static site generator
  2. Hugo: Go static site generator
  3. Far more at Static Gen.
Published (RSS)
Demetrius Michael (Email)
D3MZdem_z