I’ve added a new Jekyll plugin to my repository called Availability. It lets you mark sections of documentation based on their availability in different software builds. This post will be short as I’ve already documented it pretty well in the README, plus it will likely be of use to literally nobody but me, as it would only be useful to people running Jekyll-based documentation sites about a single Mac app that has a public beta program, which is a pretty limited audience.
But it is, in my opinion, an elegant solution to a particular problem, so I thought I’d share it anyway.
The Problem
When I add new features to Bunch, the first thing I do after testing is write the documentation. Nothing puts a feature through its paces like trying to write thorough documentation for it.
But new features are always released to the beta feed before they make it into the stable feed, and I need to have the documentation of the new features available to beta users, and I don’t want to publish a whole subsite with the beta docs. So I add the new feature documentation to the main site with a note that the feature is currently only in the beta version, which works well, but when the features in the beta move to stable, I have to go through and delete all of those beta alerts.
So this plugin lets me tie sections of text to specific build numbers. I just add a tag like:
{% available 119 %}
# My New Feature
Some documentation...
{% endavailable %}
At build time, the plugin checks my Sparkle appcast for the latest public and beta build numbers. If the marked feature has a build number less than or equal to the live release, it just gets processed as if the tag wasn’t there. If it’s greater than the public release and less than or equal to the live beta build, it gets markup to indicate it’s in the beta only. If it’s higher than the beta build, it gets marked up as an “Upcoming” feature, allowing me to document new features before they even make it into the beta without worrying that I’ll confusingly publish documentation for features nobody has yet.
You can also easily use the plugin to remove unreleased features from the output entirely just by setting the template strings to empty quotes. This allows you to write documentation ahead of time, and have it automatically appear only when the appropriate build is added to the appcast.
If you’re interested, the code is up on GitHub and you’re welcome to customize it and make it work for you.
