How This All Got Started
This is a quick technical overview of how I setup this blog and how easy it can be to start your own!
Jekyll
First off, this blog is based on Jekyll which in its own words "is a simple, blog aware, static site generator." What this really means is that it turns some simply formatted files in into full html pages for you. It does also have a built in web server, but your not really meant to use this for a full site deploy, only for testing.
This blog is based off Jekyll-Bootstrap which makes the process of setting up this blog even quicker!
To get started with Jekyll and Jekyll-Bootstrap, you will need Ruby Gems installed which is essentially a package manager for ruby programs.
If you want free hosting of your blog you will also need a github account and git installed.
Getting Started
The first thing I did was go through the instructions on the Jekyll-Bootstrap page, which told me to:
- Create a github repository, called USERNAME.github.com.
Where you replace USERNAME your github username with. This is important as once you create this repo github realises this is a Jekyll blog and turns this a github pages site. Very nice!
Then:
git clone https://github.com/plusjade/jekyll-bootstrap.git USERNAME.github.com
cd USERNAME.github.com
git remote set-url origin git@github.com:USERNAME/USERNAME.github.com.git
git push origin master
Github will then automatically turn your site repo into a Github Pages site. This may take a few minutes to update so be patient, and it will take a few minutes to update every time you push your changes.
You can actually view all the source from this blog here.
Now there are some very good resources already on getting your site up and running, and adding new posts so I recommend checking out the Jekyll documentation before going any further.
Running Jekyll and Customising
Now you will probably want to test your site locally before pushing you changes to the live site. This can be accomplished very easily using Jekyll.
jekyll --server --auto
Make sure you are in the root of your repository when you run this. This will
start Jekyll running a web server on
http://localhost:4000/. As we have specified the
--auto option to Jekyll, it will automagically compile any changes to our site
and rehost them.
If you now browse to http://localhost:4000/ you see a very generic looking blog, with a nice intro to using Jekyll-Bootstrap and Jekyll. However it doesn't have a nice blog name or any indication of whos blog it is! Lets change that.
On you file system you will need to browse to your repository and open up _config.yml in your favourite text editor. Mine is Vim, and I will certianly discuss that later...
title : Blog Title
tagline: computers. commandline. java. blog.
author :
name : Tom Cammann
email : your.email@here.com
github : takac
twitter : tea_sea
feedburner : feedname
Go ahead and change this to you own information and blog information. You can also setup Google Analytics, Feedburner and Disqus with your Jekyll blog, however this is more advanced stuff.
Once you save your details in there, you should be able to browse to localhost:4000 again and view the updated changes.
Now we have setup the config correctly we can modify our landing page, or index
page, which is set to index.md. Again open up your text editor and start
changing! The format of the files your Jekyll blog will use is based on
Markdown which allows you to
write using an easy-to-read, easy-to-write plain text format, which is then
converted into HTML by Jekyll. Again after you have made some changes to
index.md and you have saved your changes you can view the rendered page by
browsing to localhost:4000.
First Post
Now you've customised your own front page it seems like a good time to have a
go a your first blog post. Each post needs to go in the _post directory. The
filename is also very important. The filename must follow the convention:
yyyy-mm-dd-title-of-post.markup, eg. this file is called
2013-01-11-how-this-all-got-started.md. The markup as the file extension
specifies what markup language this file will be written in. I like markdown,
and I have used the markdown extension .md so I can use it.
Create a new file: _posts/2013-01-11-my-first-post.md
You must start your post with a yaml header.
---
layout: post
description: How I Created this Jekyll Blog
tags: [intro, beginner, jekyll, tutorial]
---
The layout key is the most important line. It specifies what layout template to
use when building the HTML page. All the layouts available for your site are in
the _layouts directory. This means you can also customise any of your layouts
at anytime and it will update the other posts using that layout.
The tags and description lines just specify some extra metadata for your site. They aren't necessary but they add helpful metadata which really helps for SEO.
After the yaml header in the Jekyll-Bootstrap posts, there is a strange
looking line:
This line is in the Liquid Markup syntax. It is
another markup language used within any of the pages you create that are
processed by Jekyll. This line tells Liquid to directly include the contents of
the file JB/setup. This file can also be in the same format, using Liquid
tags {% ... %} .
The rest of the content of your must be in your specified markup language, but you can include Liquid markup at any point in the document too. Lets create a header for our post, and some text underneath.
## My First Header ##
The ## signals a H2 style header, if you used one # it would be an H1 style
header, and if you used 3#s it would be an H3 style header. This text will
come out as a standard text body.
Great now we have the started our blog post, we should save and see what this renders too. If you haven't already, lets start Jekyll and go http://localhost:4000/. Jekyll can be started by running:
jekyll --server --auto
In the root directory of your blog, ie in the same directory as the _posts and
_layouts directories.
We should now see a nice clean web render of your really simple Markdown post. Great!
Additional Resources
Hopefully this helped get you started blogging with Jekyll. There are lots of other great resources out there to help you get started. Make sure you checkout the Jekyll documentation and the Jekyll-Bootstrap documentation, they were both helpful for me when starting this blog.
Another invaluable resource is the sites that other developers have created using Jekyll. The source code for many of the sites that use Jekyll are listed here. Go check them out and get inspired!
Tom
blog comments powered by Disqus