The purpose of this tutorial is to get up and running with a fully capable blog quickly and at no cost. Thats right, free. Zip … zilch … $0. If you don’t care to understand some of the underlying technology feel free to skip this overview and go straight the step-by-step guide further down.
We are going to be using the very popular Jekyll static site generator to create a great looking, and fast rendering blog that can be deployed to GitHub for free. This isn’t a hack by any means. GitHub encourages projects to host pages on their site using the GitHub Pages system. To read more about Jekyll and GitHub pages please visit their respective sites.
I wanted to make sure that this tutorial could be followed on any platform. Windows, Mac or Linux. So to do so I am going to be using Vagrant along with VirtualBox to give us a virtual environment that will offer the same experience across all platforms.
“Vagrant is a tool for building complete development environments.” Vagrant will allow us to preconfigure our blog building environment with all the tools we need to deploy to GitHub pages. I have created a bare bones Vagrantfile that has everything we need. Most notably, Ruby, Git and Jekyll. Vagrant uses VirtualBox to create a virtual machine that we can connect to to build our blog.
Jekyll is a static site generator written in Ruby. Static site generators typically use simplified markup languages such as YAML and Markdown to configure sites, create pages and posts, and compile everything down into static HTML and CSS that can be uploaded and hosted on many web storage platforms such as Amazon S3, Rackspace or in our case GitHub. Static sites offer many benefits. Most notably they are fast, do not require traditional web servers connected to databases to run, are very secure and have built in redundancy when deployed from separate machines such as in our case. This allows our blog to be fast, safe and cheap. What more can you ask for?
Markdown is a markup language or syntax that was developed by John Gruber of Daring Fireball that has spawned numerous variations. The beauty of Markdown is in the ability for a writer to just write without being overly concerned about styling which gets handled in the compilation of the site by Jekyll and any particular styling or theme you have. All posts for your blog will be written in Markdown. While Markdown can be written in a simple plain text editor, there are also some good Markdown specific editors. Here are a few for Mac and Windows that I am familiar with:
GitHub is version control and social coding platform. It is free for public projects which this will be, and allows us to manage versions of our blog site, as well as host the static files for the blog itself. You will be required to sign up for a GitHub account if you do not already have one. Head on over to this page if you need to create an account.
Note: The use of the
$ at the beginning of commands denotes the command prompt and should not be included in any of the commands below.
Step 1: Download and install Virtualbox and Vagrant for your operating system.
Step 2: Create a folder for your blog somewhere on your computer. For my example I am using a Mac and have created a blog folder here
~/dev/blog on my system. Create something similar in your User or Documents folder.
Step 3: Download this Vagrantfile and copy it to the folder you created in Step 2.
Step 4: Now from here on out you will need to work in the command line. On Windows fire up the command line by pressing
R and then typing
cmd and hitting return. Mac users can fire up their Terminal of choice either iTerm or the system Terminal. Linux users, you know what to do.
Step 5: Inside the command line navigate to the folder that you created in Step 2. For me I can type:
cd ~/dev/blog and hit enter. Make sure the Vagrantfile from Step 3 is in this folder.
Step 6: Initialize Vagrant:
$ vagrant up
This is going to create a new virtual machine for us using vagrant and virtualbox. You will see a bunch of lines scroll by your terminal window. This is just all the necessary software being installed on the machine. When it is done you will see the last line:
==> default: New Jekyll site installed in /vagrant.
This indicates everything is good and you will be placed back at the command prompt. Afterward you will have the following folder structure in the folder you initially created. This is actually now a shared folder that exists locally and on your virtual machine. Very helpful of when we go to create new posts.
Step 7: Login to the virtual machine and start the Jekyll server
Step 8: The blog should be up and running locally at this point. Check that is is working by visiting http://localhost:4000. You should This is a nice feature that will allow you to make changes to your blog, or create new posts and see how everything will look before uploading to GitHub.
Step 9: Now we can create our first blog post! Jumping back over to your desktop, navigate to the blog folder you created earlier. Inside that main folder there is a
_posts subfolder. This is where you will store all your posts. You can see that there is already an example file in there. All posts in Jekyll are writen in a markup language called Markdown. Markdown is a simple syntax that allows you to quickly draft up well formatted posts with minimal effort. For more information on Markdown refer to the Daring Fireball Syntax or the Jekyll documentation. All posts should be named folwwing the convention of the example starting with the date and then the title seperated by dashes, and a file extension of
.md, either will work. Here is the example post
2015-01-20-welcome-to-jekyll.markdown. Create a new file, for this example I will create a file named
Step 10: Lets open up the file we just created. Use any of the text editors mentioned earlier or your personal favorite. i am not going to go into all the details of the file. There is ample documentation that can be found on the Jekyll site. There are essentially two items to be aware of. The frontmatter and the body of the post. Here is an example of a simple post that I am going to paste into the file we just opened. (Credit: MarkItDown). Save this file. Make sure it gets saved to the
Step 11: Lets see our work. If you go back to the site http://localhost:4000 and refresh the page you should see the new paost we just made. If you want to automte the reloading of the page, look into a page reloading tool that watched for changes. I personally use LiveReload.
To wrap up this tutorial the only last thing we need to do is deploy our blog so that it can viewed by anyone. Keeping to the free theme of this guide we have chosen to deploy to GitHub using their GitHub Pages service. This allows developers to host static project pages but can also be used to host static blogs in our case. There is ample documention on deploying to GitHub Pages. You will first need to install the github-pages gem and make sure that you have a GitHub account and a project repository set to host your blog. The repository must be named using the
username.github.io convention which will also be the URL to your blog site. A step by step can be found at the GitHub Pages site.
Thats it! Enjoy your new, secure, fast and free blogging site!