Creating a blog with Jekyll, Poole and surge.sh

20 Jun 2015

I wanted a place to write down my notes and experiences with various technologies. Since I like learning new technologies I decided to pick a technology I had no prior experience with. This is Jekyll. Jekyll is an engine that helps generate a static website from your Markdown text files (it also understands other formats, but I will use Markdown for my blog posts). Since the site is built with Jekyll, the blog posts will be stored as text files. This makes them an ideal fit for a source control system - like Git. You can actually host your blog for free with Github Pages, which is powered by Jekyll. However that requires a public repository on Github. This is not necessarily a problem, and will work well for many blogs and projects. It could also work for my blog, but I decided to go down a different path.

I had previously come across a static website host called surge.sh - which offers hosting to static websites for free - including a custom domain name and a CDN. It is fairly simple to use, and it is a perfect fit for my blog. Using surge instead of github pages means I do not need to put the source to my blog in a public Github repository, and it means I am not relying on the Github version of Jekyll (when using Github pages, Github is running the Jekyll tool on the source automatically). I wanted more control over how the site is generated.

I still wanted to use Git as a version control system for my blog source, and luckily Bitbucket is a service that provides free private Git repositories.

The standard Jekyll site style did not really fit the style I wanted for my blog. I searched for Jekyll themes, and found a few sites that offer free themes. However the theme I went with is the Lanyon theme from Poole.

Lets get started with the blog…

Steps to set up a new blog with Jekyll, Poole and surge.sh

1. Install Jekyll

gem install jekyll

This requires that you have RubyGems installed

2. Setup the base blog:

git clone [email protected]:poole/lanyon.git
mv lanyon blog
cd blog
git remote remove origin

Now you can see the site by running:

jekyll serve

Open http://localhost:4000 in your browser

3. Setup surge

npm install --global surge

This requires NodeJS

4. Optionally create a repository on Bitbucket

If you want free version control for your blog, you can optianlly create a repository on Bitbucket

5. Optionally configure your domain

If you have a domain you would like to use for your blog, you need to add a CNAME record to point to surge:

CNAME  blog.<your-domain>.com  na-west1.surge.sh

6. Create a simple deploy script

To be able to easily deploy your blog to surge, create a simple deploy script (deploy.sh):

#!/bin/sh
jekyll build
surge _site/ blog.<your-domain>.com

7. Make the script executable

chmod +x deploy.sh

8. Run the script

Run the deploy script (./deploy.sh), and navigate to your domain in a browser (if you did not set up a domain for surge, you will get a free subdomain from surge)

Søren Pedersen