ldeck’s musings

Personal Blog with Github Pages and Jekyll themes Pt2.

2018-04-25T03:05:00+00:00

In Part 1 I said that blogging with GitHub Pages and Jekyll is a popular choice but it could be much simpler.

GitHub Pages instructions, disappointingly, left us with an index.html file simply containing the text Hello, World. As an advanced option that would be great, but but I’d hoped for a markdown-based blog site out of the box.

Jekyll’s Prerequisites

As it turns out Jekyll’s Quickstart Guide assumes you have a ruby development environment already.

See my Ruby development environment quickstart guide to fulfil that requirement for macOS.

Jekyll’s installation documentation is otherwise helpful for various platforms.

Installing Jekyll

As Jekyll’s installation documentation suggests we install both bundler to manage plugins and themes along with jekyll itself.

gem install bundler jekyll

In part 3, we’ll use look at theming jekyll.

You can also now refer again to Jekyll’s quickstart guide, it’s basic usage and various docs.

Ruby development environment quickstart guide

2018-04-25T01:00:00+00:00

Sandboxing ruby projects from external changes is imho the sensible choice.

This is true, of course, for any development environment. It’s quite frustrating to come back to a project after some time and find it broken because it depended on a particular system configuration that just worked at the time.

One of the underlying remedies for ruby is to use a ruby version manager like rbenv. So on macOS the following will do the trick.

Step 1. Install rbenv with ruby-build

brew install rbenv

Step 2. Initialise your shell with rbenv

I use bash-it, thus

bash-it enable plugin rbenv

But, it is otherwise achieved via rbenv:

# Run this and follow the instructions to set up rbenv integration with your shell
rbenv init

Step 3. Verify rbenv is setup

# assume we've opened a new terminal
curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-doctor | bash

Step 4. Install recent ruby

Now install a ruby version via rbenv.

# list the most recent stable version:
rbenv install -l | grep -E '^\s*[0-9\.]+$' | tail -n 1

# install that ruby version globally. e.g.,
rbenv install 2.5.1
rbenv global 2.5.1

Step 5. Project initialisation

# init project dir and cd into it
mkdir my-new-project
cd $_

# init .ruby-version
rbenv local 2.5.1

An alternative / complementary solution, I use direnv. See direnv’s ruby wiki page for further tips.

Personal Blog with Github Pages and Jekyll themes Pt1.

2018-04-14T00:20:00+00:00

Getting started with GitHub Pages is fairly straightforward if all you want is plain text on a white canvas.

To setup a markdown based blog, however, jekyll is a popular option.

The Good.

Jekyll has promise.

Why give Jekyll a go? My thinking was…

It’s suggested by GitHub.
It has lots of community contributed themes.
Both of these should save me time.

The end result is that it’s simple to create blog posts: create a YYYY-MM-DD-name-of-post.markdown file in your _posts directory, commit and push.

---
layout: post
title:  "Welcome to Jekyll!"
date:   2018-04-14 11:10:16 +1100
categories: jekyll update
---
Create this post in your `_posts` directory. Go ahead and edit it and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run `bundle exec jekyll serve`, which launches a web server and auto-regenerates your site when a file is updated.

To add new posts, simply add a file in the `_posts` directory that follows the convention `YYYY-MM-DD-name-of-post.ext` and includes the necessary front matter. Take a look at the source for this post to get an idea about how it works.

The Bad.

The Jekyll docs are verbose from the start.

Too much reading is given to fine-grained options, reading more like man pages, with all the options up front and any examples, if any, buried at the end.

The Quick Start Guide, ironically not linked to from Jekyll’s homepage, ends with a section called Next Steps:

Building a Jekyll site with the default theme is just the first step. The real magic happens when you start creating blog posts, using the front matter to control templates and layouts, and taking advantage of all the awesome configuration options Jekyll makes available.

This is exactly what we want to do, but there’s no link to the relevant instructions for doing this; the next button takes you instead to Installation, which presumably you’ve already done if you managed to get through the Quick Start Guide, right?

Let’s Fix That.

Providing a step-by-step guide beyond generating “Hello, World!” would have been easy. It could go something like this:

Perform the initial steps provided by GitHub Pages. i.e.,

Create a repository called yourusername.github.io here.
Clone your new repository to a local directory as GitHub describes.
Generate a Jekyll blog site (see part 2).
Generate and write a blog post (see part 2).

Commit and push.

 $ git add --all
 $ git commit -m "My initial blog site"
 $ git push -u origin master

View your handy work at https://yourusername.github.io.

Well, in part 2 we’ll move towards getting jekyll up and running.