In my last post, I used a little diagram to describe my audio setup. Some simple boxes and arrows, just like this:

{% ditaa %} +—–+ /—–
| Foo |——>| Bar | +—–+ -––/ ^ /—–+ | | Baz |—=—+ +—–+ {% endditaa %}

However, this would not be in the spirit of hacking if I prepared this with a graphics program. Instead I used ditaa to transform this ASCII text

+-----+       /-----\
| Foo |------>| Bar |
+-----+       \-----/
                 ^
   /-----+       |
   | Baz |---=---+
   +-----+

into the image above. This is working just fine but it’s annoying to

1. write the markup,
2. process it with ditaa and
3. insert a link of the generated image in the markdown document.

Sure, it would be much more straightforward to just type the ditaa markup inline into the markdown document, wouldn’t it? Because I couldn’t find a plugin that implements this behaviour, I wrote it myself. The plugin registers the ditaa block with Liquid, tries to generate an image and place the image link right into the final HTML post:

{% raw %} # My neat little boxes

{% ditaa %}
+-----+      +-----+
| Foo |----->| Bar |
+-----+      +-----+
{% endditaa %}

This is how they roll!

{% endraw %}

In case, ditaa is not installed or the image could not be generated, the plugin falls back to output the plain ASCII diagram in a <pre> block.

Limitations

With Liquid – the templating engine of Jekyll – there is only one way to implement this feature and that is sub-classing Liquid::Block. Unfortunately, a block is just supposed to generate HTML from whatever is in inside but not new assets in the file system. For generating new content, the Jekyll::Generator should be used but this is only working on a higher, per-site level.

Now, I generate an image for each ditaa block and store that in an images/ directory visible to Jekyll so that Jekyll copies it whenever it re-generates the site. So in a way, Jekyll does not know that it created that image itself. This becomes noticeable when the site is deployed without auto-regeneration (e.g. when pushing to a Git repository and generating a fresh site). In this case, a second Jekyll pass is necessary. Not cool.

PS: The ribbons

You probably have noticed the “Fork me on GitHub” ribbon. I always liked that these visual cues help people immediately recognize if there is something to check out and fork off. From now on, you will see this ribbon on all pages that feature a project that I put on GitHub, along with the Octocats  on the landing page.

I used a little Jekyll magic, to avoid putting this in manually for each post that refers to a repository: Whenever I want to link to one of my repositories, I add a repo URL variable in the YAML front matter. The Liquid template for a blog post checks if this variable exists and inserts the image template with the repo URL. Simple but powerful.