Automating HTML5 Generation with ASCII Doctor

If you’re a documentation nerd or planning to create content for publishing, surely you will encounter ASCII Doc. I first met it when I was writing a Solidity tutorial, and as someone who likes his documentation to be easy and repeatable, I fell for it almost immediately. AsciiDoc is a plain text format that you can write in any editor, and it is being used by publishing giants like O’Reilly to create books and content. If it is good enough for them, it is good enough for me.

But there was one problem I kept running into: generating HTML documents from the asciidoc format. I could write the file, run a converter by hand, and get a nice HTML page out of it, but doing that for every small edit quickly became tedious. There had to be a better way. So how do I automate it?

Better to die fighting for freedom than be a prisoner all the days of your life.
~ Bob Marley.

✅ Prerequisites

Before we start, make sure you have the basics ready. This is a small list, so it should not take long.

• Ruby 2.5 and above. You also get RubyGems along with Ruby, which is the package manager we will use to install everything we need.

That is really it. The magic happens with a few command line tools and a browser extension, and I will walk you through each piece so you know exactly what you are installing and why.

🛠️ So how do we render HTML5 from ASCII Doc?

We proceed by getting all the required gems. The first step is getting the file watcher to watch for changes in our document, so that every save triggers a fresh conversion automatically.

gem install asciidoctor guard guard-shell guard-livereload yajl-ruby

Let us break down what we just installed, because each gem has a specific job. asciidoctor is the engine that converts our AsciiDoc files into HTML. guard is the file watcher, a small daemon that monitors our files and reacts when they change. guard-shell lets Guard run commands whenever a watched file changes, which is how we trigger the conversion. guard-livereload is the piece that tells our browser to refresh itself, and yajl-ruby is a fast JSON parser that some of these components depend on under the hood.

Once the gems are in place, you will need the companion browser extension for LiveReload. The extension will be the messenger between Guard and your browser, so nothing happens without it. For Chrome, the official LiveReload extension is the standard choice.

After the installation of the Chrome Extension, you need to check “Allow access to file URLs” checkbox in More Tools > Extensions > Live Reload Details for it to work with local file URLs. This is the step that trips up a lot of people: without that checkbox, the extension silently refuses to talk to files opened directly from your disk, and you will sit there wondering why the browser never refreshes. I have been that person, so trust me, check the box first.

Now we create a Guardfile with the contents below. This file is the heart of the whole setup, think of it as a list of rules that tells Guard what to watch and what to do when something changes.

require "asciidoctor"
guard "shell" do
	watch(/^solidity\.adoc$/) {|m|
		Asciidoctor.convert_file m[0]
	}
end
guard "livereload" do
	watch(%r{^.+\.(css|js|html)$})
end

Here is what each block does. The first guard block watches for changes to our AsciiDoc source file, in this case solidity.adoc, and every time it changes, the block calls Asciidoctor.convert_file to rebuild the HTML version. Save the file, and a fresh HTML document appears, no manual steps involved. The second guard block watches for changes to any CSS, JavaScript, or HTML file and sends a signal to the browser through the LiveReload extension, so your page refreshes every time the generated output changes. You will see your updates appear in real time, exactly the way a live blogging workflow should feel.

When all is done, start the guard process to monitor and serve files. This is the moment everything comes alive.

guard start

Leave that terminal window running, and Guard will keep watching in the background while you write. Save your .adoc file, and within a second or two your browser shows the freshly generated HTML.

That’s it guys, we created our workflow for generating HTML5 using the asciidoctor format. No more typing conversion commands after every edit, just write, save, and watch the browser update itself. Hit like if you like, subs if you love and as always live life. Hope you guys enjoyed this article!