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. ASCII Doc is being used by different publishing giants like O’Reilly to create books and content.

One problem I encountered is generating HTML documents from asciidoc format. 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

• Ruby 2.5 and above

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.

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

The livereload gem watch changes in the file system. Also, you may need to install companion browser extension.

After the installation of 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.

Then we create a Guardfile with the contents below.

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

The first guard block converts file to HTML5. Then after that the second guard block watches for file changes and reloads browser.

When all is done start the guard process to monitor and serve files.

guard start

That’s it guys we created our workflow for generating HTML5 using the asciidoctor format. Hit like if you like, subs if you love and as always live life. Hope you guys enjoyed this article!