The Making Of

The concept

The idea of writing a blog came to my mind long time ago. I started two times, but finally the third is the good one. First because I found a good platform to write posts and create my own design and second because I already have a bunch of stories to write about.

This first post (the second really) is about the blog itself. Not only from the code point of view, but also from the design and concept perspectives.

The name’s origin is pretty clear. It is René DescartesCogito” with a geek twist ;) The point is that you cannot code without thinking, but… do we always think as hard as we should? For the favicon, I will let the reader find out what it is!

At the beggining I wanted to focus on the “thinking” part and Rodin’s Thinker came to my mind. Later I changed my mind to focus on the “programming side”, then I decided to use a computer picture as the background. I considered “famous” computers as HAL 9000 and Eniac, in the end I used the latter one, focusing in the old times of computing.

The looks are “old style” or “vintage” as modern people like to call it nowadays. I wanted to reflect the origins of this craft and that is why the colors are dark and greenish (like my first monitor ;)

The implementation

I saw some premade themes and sites done with Jekyll, but finally I started from scratch to have the minimal code I needed for my blog and to customize it freely from the start.

In order to blog with Jekyll, you have to install the following software in your system: Ruby, Gem , Jekyll (obvious), Python, Pygments (for syntax highlighting).

Then, to create the site structure, you have to execute the command jekyll new <user>.github.io. This will generate the minimum files required by Jekyll to build a site. The name doesn’t need to follow that naming pattern if you are going to host the site outside Github.

For the design I chose Twitter Bootstrap. Anyway I didn’t wanted my blog to look like the hundreds of sites using Bootstrap, so I looked for a custom theme. I found very good templates in Start Bootstrap. Like these two which I used for some parts of the design:

To generate the base (static) site I used html5 boilerplate (in a tool of my own called Webstrap). The skeleton generated by this tool contains: crossdomain.xml, humans.txt & robots.txt from HTML5 Boilerplate.

The icons I use are taken from Font Awesome however I created a custom font using IcoMoon for the icons I could not find there.

To make the blog lighter and easier to update, I tried to use CDNs to avoid copying libraries to my blog’s files. So most of the libraries (like Bootstrap, jQuery, Font Awesome and so on) are taken from remote servers instead of being served directly from the blog.

After this, I had all the static structure of the blog: the styles, icons, and so on. But I still had to code the templates to render content.

The most important templates are _layouts/default.html, _layouts/post.html and posts.html to develop them I took static HTMLs from the themes I downloaded and inserted the dynamic parts following the Jekyll reference which is very useful and clear.

If you are deploying in Github and the pages are not updated, check the Github repository settings (Github Pages section) to see if there is any error. Sometimes the blog builds locally but fails to render in the server (checking this can save you a lot of time wondering what is going wrong ;) trust me).

There are other templates that I picked from other Jekyll blogs, like these ones:

  • The atom.xml and _includes files were taken from the UP theme. Note that UP’s includes were modified for the blog.

  • sitemap.txt and rss.xml were copied from JekyllBootstrap.

To make syntax highlighting work, you need to install Pygments tool. It is very important that you also generate the “syntax styles” for pygments. You can do this executing the following command: pygmentize -S monokai -f html > css/syntax.css After running the previous command, do not forget to include syntax.css in the pages where you intend to use syntax highlighting!

Blog usage

To use the blog, I decided to use shell scripts instead a full blown build tool. In the end the blog has to be maintained in Unix… so who cares about multiplatform.

The scripts are inside the _bin directory and they are used to generate the themes and the icons.

To write posts and deploy them to the server, you will only need Jekyll and Git. These are the most common actions:

  • Launch blog locally: jekyll serve --watch after running that, you can see the blog in http://localhost:4000
  • Deploy changes: git add . && git commit && git push will upload your latest changes to the server.

Conclusion

Starting a blog with Jekyll from scratch is way harder than using JekyllBootstrap or other blog engine. In exchange: you get flexibility, take advantage of your current knowledge (Git, HTML…) and you don’t have to learn custom templates for closed products.

Also you will learn valuable things (about Web design and development) and have fun in the process!

As a side effect, I realized that static site generation can be useful for other purposes (not only for blogs). For example, it can be used to generate software project’s technical documentation.

Regarding the last point, I found a Jekyll wannabe in Java called JBake that looks very promising.

(Re)using it

If you want to use the code for your own site, you can refer to the readme.md file and check how to change it to suit your own needs.

comments powered by Disqus