Setting up Jekyl in a sub directory

Jekyll is a blog-aware static site generator. The operative words in that sentence being static site, there is no php, no database, running on this blog. There are few advantages to this setup over the traditional alternatives such as wordpress:

1. Speed of service: no code execution means the limiting factor is how fast the html can be served
2. More secure: no code/database means a smaller attack surface.
3. Easy blogging for someone who works in markdown or mostly pure text

It presents a few problems:

1. Large sites generate slow. Not a problem for me since I do not blog frequently.
2. The setup is not straight-forward or as painless as it might appear on first blush.

To the second point I present my experience with installing and configuring it to taste. My major deviation was to run my blog from a subdirectory on my site rather than have the blog run from the root of the site.

On the local machine:

• Install Ruby if you do not have it already.

• Install Jekyll with the following command:

gem install jekyll

• Jekyll requires a certain directory order to generate the site. Either clone someone elses basic structure as I did with Tom Preston-Werner’s. His provided a basic framework and layout to build off of. Otherwise you can clone something such as this.

• Styling the site is left to reader. All of it is done in CSS and the _layouts folder.

• The major config change to use a subdirectory is to add this line to the _congif.yml in the root directory:

baseurl: /blog

The problem with this, and it is not well documented, is that baseurl does not actually change the root of the site as far as links go. Therefore links will point to /rest-of-link rather than /blog/rest-of-link . So the following changes will need to be made to links:

{ post.url }

becomes { site.baseurl }{ post.url }

will fix the links. Obviously I left the double brackets off in the example so that they can be rendered properly.