I’ll start talking about the last thing I started to experiment with, that is this very blog you are reading right now, built with Jekyll + Octopress.
Straight-forward definition taken directy from the Github’s repository description.
Jekyll is a blog-aware, static site generator in Ruby
What does that means? The concept of Jekyll is a bit different from the usual blog engine you might be used to see arround (read: Wordpress).
The tipical blog engine is some kind of web app that integrates administration tools, 3rd party plugins, WYSIWYG editor, login system, automatic draft saving, flux condenser… and also serves your static posts. As you see, most of the features a blog platform provides are not part of a real blog’s raison d’etre, which is to publish content to the world and allow the world to reach that content. Jekyll gets rid of all these non-esential features. Is just a blog generator.
The keyword here is generator. Jekyll don’t serves your blog, it only generates the blog as a bunch of static pages. No content is built at runtime, the html is created at complilation time. This makes the blog super-simple and blazing fast from the outside. No server processing, your blog is prebuilt.
What we loss in exchange? Well, almost everything else. You don’t have an admin area, you don’t have
an online editor, but hey!
We are programmers.
- We don’t need to save drafts, we have even a better tool called version control systems.
- We don’t like text processors with lots of buttons and menus, we are used to write plain text, and we do it much faster in Markdown in owr favourite text editor.
- We don’t need to admin tools. We make changes, commit those changes and push them.
Of course, this means that Jekyll is not for everybody. Is built for people that is familiar with the development process and wants to have full control over the process. Each blog posts is placed in a markdown file (it can also be textile of just plain HTML if your prefer) following some naming and directory structure conventions, and then compiled into the final html structure that will be accessible from the outside.
Octopress is blogging framework built on top of Jekyll. It extends Jekyll in several ways, but the main ones are:
- Support for themes. Easy to install, based on HTML5 semantics, and mobile-friendly.
- Provides a complete collection of plugins for common things like comments, share in social networks and more. Since octopress is very focused into programming world, there is also plugins to embed code from files in our local system, from gists and even from github’s commits, with syntax highlighting and all the refinements you can desire.
- A collection of rake tasks that automates development and deploy.
For this tutorial I’ll be using the latest code direclty from the master branch and ruby 2.0.
The fist step is to get octopress, cloning the repo and give it the name you want for your blog.
You’ll see that octopress has a
.rbenv-version file in the root folder that specify ruby 1.9.3-p194 as the desired version.
Maybe you want to update that file to the fresh ruby
2.0.0-p0 as I did. It’s totally compatible. Living on the edge.
Now you can install all dependencies with bundler and run our first rake task to install a theme.
rake install will install the default theme, but you can install any theme you like cloning the desired
theme into the
.themes folder and run the task with the name of the theme. By example, to install the fabric theme:
1 2 3 4
You can see a list with some available themes here but there is a lot more.
The next step is to configure the basics of your blog.
Current master branch (octopress 2.0) only has a single configuration file (
Let’s fill only the minimum information.
1 2 3 4 5 6 7 8 9
The first post
Now we can create our first post. The naming convention is explained perfectly in the official documentation:
Blog posts must be stored in the source/_posts directory and named according to Jekyll’s naming conventions:
Instead of generate the file manually, it’s much easier to use the built-in rake task
rake new_post["Title of the post"]
This task creates a new post with the given title as long as some metadata used by octopress. This is the comments
of this very post.
1 2 3 4 5 6 7
And now, It’s your turn. Write somethin interesting. Remember that each time you want to see the preview, you need to regenerate the
blog, but there is another rake task for this too, the
rake preview task regenerates the content watching for changes and
starts a small server in port 4000 to serve the blog.
Take a look also to
rake generate (generates the content in the /public folder manually) and
(watch for changes into /source and /sass folders and generates the files automatically)
Deploy to github pages
Github pages is an ideal host for this kind of blogs. It’s free, fast, reliable and very very geek. In fact nowardays it has become the most accurate and widespread resume for coders, and so, github pages can be the best way to introduce yourself.
To publish your blog in github pages, the first step is to create a github pages repository. It’s really simple, and you can find the instructions here: Creating Pages with the automatic generator
Once you have finished this steps, you’ll have a repository named as
your-username.github.io, almost empty. You want to deploy your first article to
that empty repository, but you before that you should know how github pages work.
Github pages expect to have two branches, the source branch and the master branch.
The master branch is the one that github pages will show. The changes in the source branch won’t be published
until you push your changes to master. A very simple workflow we use very often while coding, applied to publishing.
You can configure those branchs manually and add your github pages repository as a remote, but there is also a rake
task that does all for you:
In the case of this blog, I ran
rake setup_github_pages[email@example.com:cibernox/cibernox.github.io.git] and the
rake deploy to upload the blog. In a snap the blog will be accessible in the url **http://your-username.github.io**.
rake deploy just generates the blog a push to the master branch. Your source branch won’t be
uploaded to github if you don’t want to. You probably want, to have a secure backup online, among other reason. Commit your
changes and do
git push origin source.
Advice for deploy
I’ve found a problem running the rake task that setups for github pages. If you have a CNAME file to specify the domain of your blog, the rake task will make some weird assumptions about naming that make the task fail. So, if you plan to redirect your domain to github pages, add the CNAME file after running this task.
Now your blog is online, so what’s next? These are only advices, but you may be interested in perform some of this tasks.
- Redirect your own domain to github pages. Because is cool to have your own domain.
- Add a entire new section. Like an about-me section (hubris is hubris).
- Add google analytics to see the visitants of your blog. Since octopress doesn’t provide administration panel, google analytics is the most convenient way to keep an eye on the traffic of your blog.
- Basic SEO. I am NOT a fan of SEO. In fact, for me is the biggest lie of the modern times. But there is a few good practices that you should follow to help google to do its job.
In the next article I’ll be covering those topics. Stay tuned.