Our release announcements (like the one for openATTIC 2.0.8) usually contain a lot of references to issues on our issue tracker in the form of issue ids like OP-XXX.

However, Nikola, the static site generator that powers this blog, did not provide an easy method to convert these issue IDs into URLs pointing to our issue tracker automatically. Converting each issue ID into an URL manually using the existing reStructuredText link syntax felt too tedious.

But fortunately Nikola provides a plugin system, that allows you to extend its functionality quite easily!

After some discussion with the Nikola developers on the #nikola IRC channel on Freenode, we came to the conclusion that the best approach would be to extend the reStructuredText markup language with an additional explicit role.

And that's what we did - our pull request was accepted and the new plugin issue_role is now available from the Nikola plugin repository.

The installation and configuration is pretty simple - simply run nikola plugin --install issue_role and configure conf.py as described, by setting ISSUE_URL in the GLOBAL_CONTEXT. In our case, we added the following to the configuration file:

GLOBAL_CONTEXT['ISSUE_URL'] = "http://tracker.openattic.org/browse/{issue}"

In our blog posts, we now enter issues as follows, and Nikola takes care of converting them into URLs:

Created plugin that automatically converts Jira Task IDs to URLs
(:issue:`OP-741`)

Running nikola build converts this into the following HTML:

Created plugin that automatically converts Jira Task IDs to URLs (OP-741)

We hope you find this useful!

Comments