I’ve been using Asciidoctor for a couple of months now and I’ve been using it a lot: for work staff, non work staff, publishing and even bloging. I had it use it so offten that I’ve noticed that whenever I would like setup it from ground up I am ending with copy/pasting the same setup. Adding guard for preview, configuring maven/gradle build scripts for creating the distributable versions. The only major problem that I see is that those setup is incoherent. I might be using browser plugin for live preview, but I don’t have full control over the entire generation process and I’m also unable to use that in repeatble way with CI server, replaycing that with a gurad script for watching the changes seams a better approach, but still I need seperate Gradle/Maven plugin with I might fail to setup identical or keep up to date.
With that in mind I have formed a set of goals of ideal tool that I would like to have:
- Repeatble and reproducable documentation “builds”
- Fine grained control of Asciidoctor settings
- Watch of the file system changes
- LiveReload in my favourite browser – (ideally the tool itself could open a tab for me and navigate to proper page)
All of that combined together within one tool: that could replace guard and any Gradle or Maven plugin, and it hit me that I can have all of that with simple Grunt setup.
Fortunetly there is Asciidoctor.js and asciidoctor-grunt that the awesome Acsiidoctor community had build and I just need to connect all dots together. I didn’t stop on creating the Gruntfile I thought that I would have now replace my setup in multiple places so it would be nice if I could done that in simple and errorless manner. So this finaly bring us to the point when I decided to create the Yeoman generator for the asciidoctor.
So let’s get it started…
And it’s done:
(this post was not inteded as walkthrough of creating the Yeomans generator if you are looking for those I highly recommend this one).
What can it do?
First of all it’s scaffolds your Asciidoctor “workspace” with some sensible defaults and some convienient directory structure.
Second of all it’s let you select your Asciidoctor stylesheet, and if you don’t like it you can re-run the generator and select a different one.
Finally it gives you build system that you have control over and you can easly integrate with your project builds.
Last but not least run
grunt serve to automaticly see your work in your favourite browser and be able to track all the changes with livereload.
It’s still in it’s early stages so I am looking for feedback on how it can it be improved, despite that from now on this will be my tool of choice.