A description of my blogging setup.
I’m Igor … wait. To learn more about me or my motivation go and read the about me page. The very first post will be meta. It describes and praise my blogging setup. It should give you a solid idea which tools I use and how to configure a similar stack. I try to list its pros and cons and share my personal opinion on the various quirks. Hope you will like it!
The keyword to my setup is Jekyll.
Jekyll is a blog aware static site generator. I use it to generate
html pages from the markdown documents. It allows specifying a
common layout and then focus only on the content. It takes your
markdown posts, converts them to html and injects the content into the
layout. It also takes care of generating a structure of folders, so
your urls can be nice and blogish,
From this point on it is straightforward - when Jekyll has done its job you’ve got a directory containing a set of html files - a full website which can be served from any static webserver like apache. I push the content to my server from where Nginx serves it.
Jekyll is a small piece of code written in ruby. It’s straightforward to install it on ubuntu.
I’m not a ruby programmer, so this may be a con from my perspective. On the other hand, you do not need to dive into the code to use Jekyll.
To use Jekyll in your project you need to prepare a directory structure:
. ├── _includes ├── _layouts ├── _plugins ├── _posts ├── _site ├── _config.yml └── index.html
Jekyll browsers your directories and parses any file starting with a yaml front matter, for example:
_config.yml is a configuration file for Jekyll. Your posts go to
_posts directory. A base template stays in the
_layouts and you
can put reusable chucks of html in
_includes. Jekyll’s behavior can
be customized with a set of plugins. They go to the
Firstly, Jekyll converts markdown/textile files into html. Htmls are considered templates and run through a liquid processor. It allows you to use constructs like loops, conditions and filters in your pages. For example, this can be used to generate a list of all posts for your archive.
Generated html is copied to
_site directory. An example from my
_site/ ├── 2013 │ └── 03 │ └── 22 │ └── meta-blogging-jekyll-setup.html ├── about.html ├── index.html ├── rss.xml └── static ├── bootstrap │ ├── css │ │ └── (...) │ ├── img │ │ └── (...) │ └── js │ └── (...) ├── css │ └── geekigor.css └── img ├── linkedin-icon.png ├── mail-icon.png ├── rss-feed-icon.png └── twitter-icon.png
Markdown is a lightweight markup language. It is a plain text, easy to read and easy to write format, which can be converted to valid (X)HTML. The format is quite popular, most notably in sites like stack overflow and github. An example of its syntax:
With markdown you can use any text editor to create the posts. No need to run a web browser and type your thought into one of these small, ugly text areas. As matter of fact, for me any text editor is emacs.
It seems natural to version control the blog as well. Since markdown is a plain-text format it is a perfect fit for git or any other VCS.
I turns out that a lot of blogs are stored on github. Just go there to find some inspiration or see how people use Jekyll.
Jekyll leaves you with a static web page, which is great. No need for a database or an application server. All you need is a plain old webserver like apache or nginx.
The usage of static html has many benefits: * it scales, * it is easy to deploy, * hosting is cheap, * no moving parts that hackers can get to.
You can host your blog on github. Github pages is a free and easy to use solution to host a static content. It can be connected to your domain. It’s not as flexible as a web server, yet it is powerful enough for many scenarios.
Out-of-a-box Jekyll is really a plain vanilla system and you need to do some work to get the features which are usually taken for granted on modern web pages.
Please note there are projects like Octopres which aim to deliver a preconfigured and themed Jekyll - so you can start right away. Even if you don’t want to use their solution it’s worth to go through its source code for idea to organize and customize your setup.
To publish an rss feed means essentially to prepare a template (we can
rss.xml) which will take your latest posts and generate a
file compliant with the RSS specification.
I started from this rss.xml file and ended up with something like that:
It generates a header for the feed, then iterates through the latest five posts and puts them in the feed.
You should also attach the feed address to
head section of your
pages. Just like this.
It will result in an icon which indicates that a feed is available.
Jekyll uses a plugin mechanism to let the world extend
its behavior. To install a plugin just drop a ruby file into the
Since I do not do ruby I need to use plugins released by the community. A following scenario may be a good example of how plugins are useful.
You need to be able to extract a lead of an article. Be it the first paragraph that you want to include on your homepage and in your rss feed. Nobody will click on a title alone, so we need to let our visitors peek into an article - to catch their interest.
Such a future is not available in a latest version of Jekyll in ubuntu
Jekyll 0.12.1). Hence we need to find a plugin. I use
this one: excerpt.rb. It simply exposes
excerpt as an
attribute of a post.
A lot of blogs on Jekyll does not use pagination at all! People tend to have a flat list of their articles, containing only titles. This approach for sure lets you compress a lot of posts on your homepage, but it just does not feel right for me. I wanted to have more blogish approach. Namely, a few posts with their excerpts on the home page and a pagination to access older posts.
Luckily there is a built-in solution. It’s described on the
Jekyll wiki. You need to set up how many posts
per page should be present. This is done in your
And then you add some liquid syntax on the home page. Here’s an example from this blog:
I’ve put it in the
_include directory as
pagination.html and set
it up on home page like this.
That’s the hard part. At least it used to be. A clean, browser compatible and good looking design is hard to achieve. Especially that, nowadays, you’re expected to cover mobile devices as well- your design needs to be responsive.
Luckily, there is a hope for us. It’s called [Bootstrap][bootstrap], it’s from twitter and it’s hot. Believe it or not, but hundreds of pages nowadays base their layout on bootstrap.
Bootstrap calls itself a front-end framework. It provides a layout, i.e., a responsive grid, a lot of components, and a ready-made design in a form of cascade style stylesheets. If you don’t like its default look, or just want to stand out from the crowd, there are good-quality themes, both free and paid, available at bootswatch. Bootstrap csses are very clean and therefore it is easy to customize it if you so wish.
In a truly agile sprint I decided to prioritize my features and deliver a working software with only a subset of them. As a part of the first iteration of course.
Couple of items are missing and I hope to add them in near future. On my short list are currently:
Another open question is how to handle images. I keep the source code for this blog in a repository, but I do not want to bloat it with images accompanying posts. There are some options here to evaluate.
The csses attached to this page are not optimized or mimified in any way. It seems a waste not to optimize them. I do not want to do it manually, therefore I need an automated process to do it for me. This process will be also useful for building and pushing the blog content to my remote server. Automation is very high on my priority list.
My current version of “About Me” sucks. I need to work on that. Also, there is a lot of nice examples of 404 pages out there. Need one for this weblog.
I have a vague plan to attract a lot of traffic to this weblog using my twitter account.
Apart from that, I plan to include comments on the site.
Sounds nice, but it means simply to have a page archiving all posts under a given tag and to link to similar posts in an automated manner.
Emacs rocks. Period. And it’s great for markdown.
However I heavily rely on org-mode as a note-taking tool. Org-mode has a great html exporter. There should be a way to combine it with Jekyll and write my posts with the org syntax.
Time to do some real work. I hope more posts will follow, and moreover, I hope they will be useful.