Thoughts by rafeca

Creating responsive emails

2012-11-04T00:00:00+00:00

There is a lot of buzz right now about responsive web design, lots of designers, developers, UX experts and marketing people are talking about it and several major companies have already migrated their web sites from two specific versions for mobile and desktop to a single responsive design.

Something really surprising is that emails have been ignored when talking about responsive design, and everybody seems to assume (wrongly) that responsive design only affects to web pages.

In fact, emails have been hated by web developers and designers for years... nowadays, nobody likes to go back to the 90's and create table-based layouts with inline CSS and not being able to use most of the CSS properties (even basic stuff like the float property is not safe to use on emails)...

But this is not an excuse to ignore the email: lots of companies rely more on their email campaigns than on their website so they can't just ignore their increasing mobile users.

Why responsive?

First of all, because there is no alternative: in opposition to web sites, on email if you want to target your mobile users the only way to do it is by using a responsive design (well, you could ask them what kind of email they want to receive, but this isn't useful on most cases when users check their emails from several devices).

Secondly, because we can. Thanks to the smartphones and the email clients they feature (which are almost the same as their web browsers), we are able to add tons of CSS3 magic to our emails (and this includes media queries!).

Design principles

It's important to notice that we have to keep supporting old email clients and webmail clients... So I'm sorry, but we won't be able to get rid of the table layout... this means that the email structure will be almost the same as regular emails.

My main advice on email designs is to keep them simple: for example try not to emulate background images by creating huge tables with tons of cells with images inside.

Instead of this, a simple layout should do the work. If you want to add any elaborated element or effect, just use CSS/CSS3 providing a fallback for old Email clients (as you would do in regular web development). This technique is useful for border radius and background images.

Also, another tip for making your life easier is to use single column layouts: it will be much easier to make them responsive.

The previous example corresponds to one the giffgaff campaign emails designed by @bipolarArtist. The design is really simple and clean, which makes it easy to implement as a responsive design.

Even though, it has two subtle effects that have been implemented using CSS rules not recommended for emails:

<table class="box" width="580" cellpadding="0" cellspacing="0" border="0" style="border-radius: 7px;">
  <tr>
    <td class="boxcell" width="580" style="background-image: url(black-triangle.png);">

Rules like border-radius and background-image won't be supported by all the email clients, but this is not a big deal as long as the email still looks well on those clients:

The same mail displayed on "old" email clients

Making it responsive

When an email is opened from a mobile device (like an iOS or Android device), the email client rescales the email viewpoint to make it fit horizontally on its screen. This makes the text, images and all the details almost unreadable. And even though most clients keep a minimum font size for texts when zooming out, this size is not big enough to be confortable to be read:

Adjusting the email container width

The first thing to do to make it look better is to change the main container width to fit the mobile screen size, so this way the mail client won't need to rescale it. To do so, we can use CSS media queries (notice that smartphone email clients, as opposite to webmail clients, are able to read CSS properties not defined inline):

<style>
@media only screen and (max-width: 480px) {
  /** your mobile styles go here **/
}
</style>

Now, inside the media query, we should redefine every table width to match the mobile horizontal size. If desktop emails use 600px as a standard width, 320px is a good size to choose for the mobile version.

@media only screen and (max-width: 480px) {
  table[class="box"], td[class="box"] {
    width: 300px !important;
  }
}

(Note that attribute selectors are being used to prevent Yahoo! Mail from displaying the mobile version).

All the tables in the email should be modified in the media query (to make them smaller), so this is why I recommend keeping the layouts simple and use as less tables as possible.

Adjusting other stuff

Just changing the table widths won't be enough in most situations: if the email contains big images they'll prevent the tables to become thinner... so we'll have to reduce the image sizes as well.

The most efficient way to do so is by setting a max-width for all the images:

@media only screen and (max-width: 480px) {
  table[class="container"] img {
    max-width: 100% !important;
  }
}

Also, we can change font sizes, margins, and even hide elements... whatever is needed to make the email look good on smaller screens.

With a few adjustments we'll get an email with nice big fonts which is easy to read in mobile devices:

Using mobile specific images

As you may have noticed in the previous screenshot, reducing image dimensions to fit them in the screen may lead to too small images that don't look well.

To fix this, we can replace the big images by their mobile optimized versions. This can be done inside the media query, but we must create a rule for each image.

First of all, we should put the image element inside a parent element that can be uniquely identified on the CSS:

<div id="info-goodybags"><img src="gfx/info-goodybags.png"/></div>

Now, we should hide the image tag and apply a background image to the container element inside the media query:

@media only screen and (max-width: 480px) {
  div[id="info-goodybags"] img {
    display: none !important;
  }

  div[id="info-goodybags"] {
    background: transparent url(gfx/info-goodybags-mobile.png) no-repeat;
    width: 210px;
    height: 139px;
  }
}

With this, we can use a smaller image for mobile that won't be scaled down on mobile devices and therefore it will look much better:

Main problem here is that there is no automatic way to replace all the images by its mobile version without having to do it one by one (and setting in the CSS the image width and height), so this becomes a time consuming job in emails with lots of images.

Using high resolution images

Emails can also contain images optimized for high pixel density screens (like the retina displays). Again, it's easy to replace a single image by its high-resolution alternative, but it becomes a crafting job to do this for lots of images.

Using media queries we can target mobile devices with high-resolution displays and make them render the optimized images:

@media only screen and (max-width: 480px) {
  div[id="info-goodybags"] img {
    display: none !important;
  }

  /* Image for mobile */
  div[id="info-goodybags"] {
    background: transparent url(gfx/info-goodybags-mobile.png) no-repeat;
    width: 210px;
    height: 139px;
  }

  /* HiDpi image for mobile */
  @media (min-device-pixel-ratio: 2.0) {
    background: transparent url(gfx/info-goodybags-mobile@2x.png) no-repeat;
    background-size: 210px 139px;
  }
}

Note: We can also provide high resolution images for the desktop version of the image, but this would mean creating yet another CSS rule and another version of each image and another and in this case it wouldn't be available to most email clients (remember that webmail clients like Gmail doesn't support CSS selectors).

Working with multiple columns

As I said at the beginning of the post, I don't recommend having multiple columns in responsive emails: it adds even more complexity to the layouts and in most cases single-column emails are simpler and cleaner.

Even though, in some situations it's nice to have several columns in the desktop version, which may be displayed as a single column in the mobile version:

The footers of emails usually have multiple columns to accommodate all the links

To do so, we should have an html like:

<table class="linkstable" width="540" cellpadding="0" cellspacing="0" border="0">
  <tr>
    <td class="linkscell">
      <table width="180" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td>
            <!-- content of first column -->
          </td>
        </tr>
      </table>
    </td>
    <td class="linkscell">
      <!-- (...) -->
      <!-- second column -->

As you can see a nested table inside each column is needed, which makes HTML more verbose and complicated.

Now, to display these columns as a single column in the mobile version, we have to redefine the style again using media queries:

@media only screen and (max-width: 480px) {
  table[class="linkstable"] {
    width: 260px !important;
  }

  table[class="linkstable"] .linkscell {
    display: block;
  }

  table[class="linkstable"] .linkscell table {
    width: 260px !important;
    margin-top: 15px;
  }
}

The important rule here is the display: block. It will make the table cells behave like regular block elements and then they will be moved one at the bottom of the other:

Conclusion

If your company uses email as an important marketing resource and you are not sending responsive emails yet, you are loosing money. There is no technical or business reason to not switch to responsive emails. So if you have the needed resources, redesign your emails and create a responsive version and your conversion rates on mobile will be improved immediately.

Update

I have opensourced this whole responsive email as a template, to serve as inspiration to future readers. You can find the code in GitHub.

Automate your release flow

2012-01-17T00:00:00+00:00

When working on an opensource project or library, it's really important to release often new versions and to document them properly.

In this post I'm not going to talk about the benefits of frequent releases in software development, I'm just going to help you to mitigate the main problem associated to frequents releases: The release overhead which is the time you spend on preparing each release. This overhead is not that big at first, but when releasing really often it becomes a boring repetitive time-consuming task that could eventually make you release less often.

The most efficient way to reduce this overhead is by automating most parts of the release process, with the help of the tools you use on your daily development process.

First of all, let's detect the most common steps involved in a release:

Implement the release features.
Increase the version of the library.
Update the changelog with all the relevant changes since last version.
If you've accepted pull requests or contributions, give some credit to the new contributors.
Update the library website of the library with all the new info above.
Push all the changes to the GitHub repository and create a tag for the new version.
Publish the new version to the correspondent library repository.

Once all those steps are done, then you can start working on the next release and repeate all the steps again.

1. Implement the release features

Although this step does not really belong to the release process, this is the most important thing to do in a release: if you don't add anything new or fix something in your library, there is no point doing a new release, it's important to plan which kind of release you're planning to do (major, minor, bug fix) and what changes are you going to include.

Before starting the development of your next version, you should update your library's README file to reflect the new usage options that the new version will have (if any). This will guide you through the development process like some kind of specification and you'll get the benefits of the Readme Driven Development.

You should try to keep the documentation really simple: In most cases just a README.md file with some simple usage examples are enough.

If you need more in-deep examples, you can create them in the examples/ folder. If you document the using inline comments with the Dooco syntax, you'll be able to transform them to beautiful HTML files with all the comments displayed alongside the code.

Also, I recommend you to create a new branch for the release, commiting all your changes there, and once done then merge them to the master branch.

2. Increase the version of the library

Once all the changes are implemented and tested (all your tests pass ‐ you're doing TDD, don't you?) and the README is updated, it starts the release process.

First thing to do is to increase the library version. In some place in your library you must define the current version. If you're planning to publish your library to a package manager you should insert the current version in some specific place (for example in the gemspec file for RubyGems or in the package.json file for npm).

It's recommended to define the package version in just a single place, if you need the library version somewhere else you should get it from this single place where it's defined.

For example in Node.js packages, if you want to make the version available to the outside, it's good to do the following:

exports.version = JSON.parse(
  fs.readFileSync(__dirname + '/../package.json', 'utf8')
).version;

This way you only have to change the library version in a single place, so it will be easier to create an script that parses this single file and updates the version.

3. Update the changelog

Keeping an updated changelog manually is a tedious task, so there are a lot of developers who don't do it at all. Even though, you should create it and mantain it updated: it will become really helpful for the developers using your library.

The standard in most GitHub projects is to use a file called History.md located in the root of the project. The file should be written in Markdown format and should contain the full library changelog.

You can format this file using your preferred layout, it's important to specify the version dates and to format it clearly. This is the layout I use:

### 0.1.3 — *November 17, 2011*

  * Fixed the GitHub publishing of tags in the jake task
  * Updated package.json to make it compatible with Node.js 0.6.x
  * Updated travis YAML file to use the new Node.js support on Travis

### 0.1.2 — *November 14, 2011*

  * Updated Jakefile with tasks to automate publishing new versions
  (...)

The best way to automate the generation of this file is by getting all git commit messages since last version. If you commit your changes using well formed commit messages, then each commit summary can be used as a single bullet point in the changelog.

How can this be achieved? It's very easy: with git and the following single line command you can get all the changes since last created tag.

$ git log `git describe --tags --abbrev=0`..HEAD --pretty=format:"  * %s"

This command prints all the changes between some initial revision and the HEAD, formatted as a plain text bulleted list.

The initial revision is calculated using the command git describe --tags --abbrev=0, which outputs the most recent tag that is in the same branch as the current HEAD.

4. List all the contributors

It's important to give credit to the people who contributes to your library: this way you may encourage more people to join to your project and help you.

An standard way to do it is by creating an AUTHORS file in the root of the project with the following format:

John Doe <john_doe@foo.com>
Chuck Norris <chuck@norris.com>
Bruce Wayne <dark_knight@gotham.com>
(...)

To get all the contributors, git is there again to help you: you can get all the commiter names and their email address by calling the following command:

$ git log --all --format="%aN <%aE>" | sort -u

So you just have to replace all the contents in the AUTHORS file by the output of the command above.

5. Update the library website

It's nice to have a public website for your library: It gives you more visibility on the Internet and it can display your package documentation in a more personalized way. GitHub allows packages to have a public web site with static pages, so you don't need to pay for a host and you can update your package site directly with git.

Creating the main page based on README file

I recommend you to reuse the main README.md file of your library for the public site: if your readme is good enough it will be more than enough, and this way you won't have to update two different things each time you modify your library (remember you dont' want to repeat yourself!).

For doing so, you must use a markdown parser that outputs mardown code to HTML. You can use the official one, or use any markdown library written in your library language.

An easy way to generate a full HTML file from a Markdown is by using two partial HTML files (a header and a footer) and then insert the markdown output within them.

The header partial file would look like:

<!DOCTYPE html>
<html>
  <head>
    <title>My awesome library - a library full of awesomeness</title>
    <link rel="stylesheet" media="all" href="stylesheets/main.css" />

    <script type="text/javascript" src="javascripts/sh_main.min.js"></script>
    <script type="text/javascript" src="javascripts/sh_javascript.min.js"></script>
  </head>
  <body>
    <a class="forkme" href="http://github.com/rafeca/awesome" title="Fork me on GitHub">
      <img src="gfx/forkme" alt="Fork me on GitHub">
    </a>
    <div id="container">

And the footer file like:

</div>
    <script type="text/javascript">sh_highlightDocument();</script>
  </body>
</html>

Between the header and the footer files you can add as much information as you want, for example the changelog, the contributors and even the license:

$ (markdown README.md && markdown History.md && markdown AUTHORS && markdown LICENSE) | cat docs/_header.html - docs/_footer.html > docs/index.html

This command will insert the output of the four markdown files between the _header.html and _footer.html files and then save the resulting file as index.html in the docs/ folder.

If you prefer to have multiple pages in your site instead of one large page, you can still do it by calling the previous command multiple times with different contents:

$ (markdown README.md) | cat docs/_header.html - docs/_footer.html > docs/index.html
$ (markdown AUTHORS) | cat docs/_header.html - docs/_footer.html > docs/authors.html
$ (markdown LICENSE) | cat docs/_header.html - docs/_footer.html > docs/license.html

Creating the example pages

As I said before, Docco library parses regular code files and transforms them to HTML files with all the comments displayed alongside the code.

Executing the Docco command is trivial:

$ docco examples/*

This will create an HTML file in the doc/ folder for each file in the examples/ folder. It will also create a docco.css which will make the HTML example files look beautiful.

Creating/updating the gh-pages branch

Now you have the full public site inside the docs/ folder, which will look more or less like this:

$ tree docs/
docs
├── example1.html
├── example2.html
├── docco.css
├── index.html
├── images
│   └── logo.png
├── javascripts
│   ├── sh_main.min.js
│   └── sh_javascript.min.js
└── stylesheets
    └── main.css

What we want to do now is to move all those files to the gh-pages branch to allow GitHub to create our repository Page.

To do so, most developers create the gh-pages as a new root branch and then copy manually all the files in the docs/ folder to the gh-pages branch and then commit the changes. This approach is totally valid (actually, GitHub Pages instructions recommend to do it this way). Even though, if you use this method you'll end up having the gh-pages branch completely independent from the master branch (so both branches won't have any relashionship and then it'll be hard to know which revision of the library the web site is from).

Check this screenshot of the network graph of a regular library (the Mocha test framework):

As you can see, the gh-pages branch goes independently of the master branch.

So, a better way to copy the docs/ folder to the gh-pages branch is by creating the gh-pages branch as a regular git branch, remove everything from the branch but the docs/ folder and move the docs/ folder to the root of the branch. The final step is commit everything in the gh-pages branch.

To do all this we only need the following 4 commands:

$ git checkout -b gh-pages
$ ls | grep -v docs | xargs rm -rf
$ git mv docs/* .
$ git commit -a -m "Initial commit in pages branch"

This has to be done only once: once the branch is created, everytime you want to update the gh-pages branch you only have to merge the changes from the master branch:

$ git checkout gh-pages
$ git merge -s subtree master

It's important to specify the Subtree merging strategy when performing the merge, this way git will detect that all the changes in the docs/ subfolder have to go to the root folder and you won't get any conflict when merging.

With this last way of copying the site to the gh-pages branch, we get the following history tree, which shows clearly the relation between the public site and the library code:

6. Push all the changes to GitHub and create the tag

Now that everything is ready, you only have to create the git tag and push everything to GitHub:

$ git tag 1.0.0
$ git push origin master gh-pages 1.0.0

7. Publish the new version to the correspondent library repository

This last step depends on the package manager where you want to upload your library. Most package managers provide really good tools that simplify a lot the upload process... for example, if you use RubyGems you'll only have to do:

$ gem build myawesomelibrary.gemspec
$ gem push myawesomelibrary-1.0.0.gem

Or in Node.js if you are using npm it's even simpler:

$ npm publish

One more thing...

If you are developing Node.js packages, you can check out my Release Tools package, which implements all those automatisms (some of them are even improved) and exposes everything in a very simple API. For instance, the whole previous release process can be automated using the following task:

releaseTools = require('releasetools');

Step(function(){
    releaseTools.updateVersionInPackageJson('minor', this)
  }, function(){
    releaseTools.updateChangelog(this)
  }, function(){
    releaseTools.updateAuthorsFile(this)
  }, function(){
    releaseTools.createExamples(this)
  }, function(){
    releaseTools.commitToGit(this)
  }, function(){
    releaseTools.createSite(this)
  }, function(){
    releaseTools.updatePagesBranch(this)
  }, function(){
    releaseTools.pushToGit(this)
  }, function(){
    releaseTools.npmPublish()
  }
)

html5 web notifications

2011-11-15T00:00:00+00:00

One of the HTML5 features I've played with recently is the Web notifications API, which adds desktop-class notifications to the browser.

Compatibility

The web notifications spec is still an early draft so it's subject to change, and the only browser implementing it is Google Chrome (all the other browsers are not planning to support it in short-term), so Web notifications are only suitable for use in few very specific scenarios... use them with care!

Who's already using Web notifications

As the spec and the first implementation of Web notifications were written by Google, they were the first to use them in a real world product: in fact Gmail has been using them for several months.

How to use them

To use the Notifications API, first of all you have to let the user grant permissions to your page to show notifications.

To do so, the first to do is to check if she has already granted the permissions by calling the checkPermission() method. This method returns 0 in case the user has already granted permissions and 1 if not:

// function to check if the user has already granted notification permissions
var hasNotificationsPermissions = function() {
  // Check if the browser supports notifications
  if (window.webkitNotifications) {
    return window.webkitNotifications.checkPermission() === 0;
  } else {
    return false;
  }
};

And then use the previous function to create the method askForPermissions():

// function to ask for notification permissions if the user hasn't done it already
var askForPermissions = function askForPermissions() {
  if (window.webkitNotifications && !hasNotificationsPermissions) {
    window.webkitNotifications.requestPermission();
  }
};

Also, it's very important to point out that the requestPermission() method only works when it's been triggered by a user-generated event, like a click or keypress event (to prevent unsolicited requests). So we have to create a button in our app to ask for notification permissions:

<button id="notification-permissions">Ask for notification permissions</button>

<script type="text/javascript">
document.querySelector('#notification-permissions').addEventListener('click', askForPermissions);
</script>

Once the user clicks on the button, she will get a popup which asks her to grant the website permissions:

Once she clicks on "Allow", we'll be able to start sending notifications. As the notifications are displayed indefinitely (once created they never disappear), I use a simple wrapper function to send notifications with a timeout:

// Sends a notification that expires after a timeout. If timeout = 0 it does not expire
var sendNotification = function sendNotification(image, title, message, timeout, showOnFocus) {
  // Default values for optional params
  timeout = (typeof timeout !== 'undefined') ? timeout : 0;
  showOnFocus = (typeof showOnFocus !== 'undefined') ? showOnFocus : true;

  // Check if the browser window is focused
  var isWindowFocused = document.querySelector(":focus") === null ? false : true;

  // Check if we should send the notification based on the showOnFocus parameter
  var shouldNotify = !isWindowFocused || isWindowFocused && showOnFocus;

  if (window.webkitNotifications && shouldNotify) {
    // Create the notification object
    var notification = window.webkitNotifications.createNotification(
      image, title, message
    );

    // Display the notification
    notification.show();

    if (timeout > 0) {
      // Hide the notification after the timeout
      setTimeout(function(){
        notification.cancel()
      }, timeout);
    }
  }
};

As you can see, this wrapper function has also a last argument called showOnFocus, which allows restricting notifications only when the browser window is not the active window in the desktop. When no timeout or showOnFocus parameters are specified, it behaves just identically as the original browser method.

Finally, this is how web notifications look on OSX (using Google Chrome, of course):

Scope of usage

As I said before, Web notifications are only available on Google Chrome, so the usage scope is really reduced; I would only recommend using it if:

You are Google.
You are doing some proof of concept of HTML5 features.
You provide a good fallback mechanism for notifications on the other browsers (for basically the 80% of your visitors).
You are developing an application for the Chrome Web Store.

In fact, I've been testing the Web Notifications in this last scenario, which is a perfect scenario for Web Notifications as all the visitors will use Google Chrome for sure. Also, having desktop-class notifications in an application is really useful, no matter if the app is being executed on a browser.

Improvements needed in the Notifications API

Although all of this sounds good, there are some flaws in the current specification of Web Notifications:

There is no way to only send notifications if the browser window is focused, this is a must as most times you only want to send notifications when the user has the browser window on the background and can't see the messages rendered on the browser window.
There is no way to show notifications that expire, why the heck do I want to show a notification that stays in the user's desktop forever? There should be a timeout param in the Notifications API.

Also, the current implementation on Google Chrome would improve a lot if instead of using its own notification display system, it were integrated with external notification systems like Growl or libnotify.

Creating this blog

2011-11-09T00:00:00+00:00

Ok... creating a blog and start talking about how you have created it looks a little bit useless... but at least this is much more useful than a Hello World post, so in this first post I'm going to explain a little bit how I set up everything.

Choosing Jekyll as a blog system

Instead of using a more classic blog system like Wordpress or Drupal, I decided to try Jekyll, which is a static site generator written in Ruby. It does not require any DB and it doesn't have any dynamic generated page: it just parses a set of plain text files that contain the posts and templates and generates static HTML files that can be served with any Web Server.

There is a lot of info on the net about Jekyll, you can find out more about it in its official wiki.

Jekyll has a lot of advantages (and some disadvantages, also), those are the ones that made me choose it:

Posts are Markdown files

As I said above, Jekyll gets the blog contents from regular text files. Those text files can have HTML code, Textile or Markdown.

I've been using Markdown lately, and I find it very simple, super-easy to learn and very readable, so in my opinion it's the best format for writing blog posts.

It's customizable

As Jekyll creates the static HTML pages by just inserting the posts inside some defined templates, so I can create line-by-line the HTML of the pages very easily.

This is cool, I don't have to modify some thousand-lines-html-templates with complex structures and tons of config parameters (the same applies to those insane CSS files) anymore.

GitHub hosting

Well, it turns out that GitHub pages support Jekyll, so just by creating a GIT repository with a Jekyll blog, GitHub automatically creates all the blog static pages and each time I push new code, the blog is regenerated... an awesome hosting for free!

GIT workflow for blogging

It's awesome to have all my posts on regular text files inside a GIT repository, so every time I push my last commits I am publishing my pending posts.

I can even create branches for writing drafts, notes, or just vague ideas about possible future posts, and once I finish writing the post I merge to master and voilà: the post is published.

No web interface

I write my posts using TextMate or VIM, and publish them using the command line via GIT, this is my regular workflow when I develop so I'm very comfortable with it.

I can do everything while offline and I can automate some tasks thanks to ZSH scripts or GIT commands.

Ok, now let's talk about real stuff... Those are the basic steps I followed to create this blog,

Creating the templates

This was actually the easiest part, I just created the main layout in _layouts/default.html and a layout for the posts in _layout/post.html, which inherits from the main layout. Jekyll uses the Liquid template engine, which has the following beautiful format:

<!DOCTYPE html>
<html>
  <head>
    <title>{{ page.title }}</title>
  </head>
  <body>
    {{ content }}
    <ul class="posts_list">
      {% for post in site.posts %}
        {% include post.html %}
      {% endfor %}
    </ul>
  </body>
</html>

You can check both templates in my GitHub repository: _layouts/

Code highlighting

Liquid automatically parses source code and highlights it when it finds the highlight tag:

{% highlight javascript %}
  setTimeout(function(){
    console.log('world');
  }, 100);
  console.log('hello');
{% endhighlight %}

But when I was creating the blog, the last version of Liquid was the 2.3.0, which had a bug on code highlighting that made it crash, so I had two options:

Downgrade Liquid version to 2.2.2
Use RedCarpet, a Markdown parser created by Vicent Marti, a Catalan GitHub employee.

Obviously, I chose the second option ;) To change the markdown parser in Jekyll, I had to add a new config parameter in the Jekyll _config.yml file:

markdown: redcarpet

Adding comments

As Jekylls creates static pages for the blog, it doesn't provide comments on the posts. So I found 3 different options to solve the issue:

Don't provide comments justifying that nobody is going to comment on blog like this one.
Use GitHub issues to host the comments, as it is explained here. This is a really cool hack, but I didn't want to force readers to have a GitHub account and I wanted to allow writing the comments within the blog.
Use DISQUS, which is a third party commenting system that provides a Javascript widget to embed comments to any page.

At the end I opted for DISQUS, because it provides all the functionality that I need. Even though I don't really like its UI and I had to tweak some of its CSS classes to make it fit properly in the design... So maybe in the future I switch to another commenting system

Other fun stuff

I wanted to have a way to list all the posts with a certain tag, and to accomplish it I needed to create a static page for every tag, which would look like this:

---
layout: default
title: Thoughts by rafeca
---
<h1>Thoughts by rafeca</h1>
<h2>Posts in category "git"</h2>
<ul class="posts_list">
  {% for post in site.categories.git %}
    {% include post.html %}
  {% endfor %}
</ul>

To create all those pages I used a Rake task (Rake is a build library for Ruby). I opted to use Rake because Jekyll is written in Ruby, so this way I could access natively to the Jekylls API to get the list of tags.

This is the Rake task that I'm using (it's a slightly modified version of this Gist):

desc 'Generate tag pages'
task :tags do
  puts "Generating tag pages..."
  require 'jekyll'

  options = Jekyll.configuration({})
  site = Jekyll::Site.new(options)
  site.read_posts('')
  site.categories.sort.each do |category, posts|
    html = ''
    html << <<-HTML
---
layout: default
title: Thoughts by rafeca
---
<h1>Thoughts by rafeca</h1>
<h2>Posts in category "#{category}"</h2>

<ul class="posts_list">
  {% for post in site.categories.#{category} %}
    {% include post.html %}
  {% endfor %}
</ul>
    HTML
    File.open("tag/#{category}.html", 'w+') do |file|
      file.puts html
    end
    puts 'tag/#{category}.html generated!'
  end
  puts 'Done!'
end

As you can see I'm iterating over all the Jekyll categories and creating the HTML file for each category. Pretty simple, huh?

So, this way the only thing I have to do before committing a new post is to execute the Rake task:

$ rake tags
Generating tag pages...
Configuration from _config.yml
tag/blog.html generated!
tag/git.html generated!
tag/markdown.html generated!
tag/ruby.html generated!
Done!

Conclusions

Now I can write my posts using VIM, and publish them via the command line with GIT, this way I feel much more comfortable while writing, and I hope this will help me write more and keep the blog updated :)