Code the Docs Blog

Asciidoctor, Jekyll, and Hyde for Elegant Docs out of the Box

I swear I don’t just love this stack because of the title it gives me. I do admit “Hyde” wouldn’t have made it into the title if it didn’t just sound so good, but it’s also a nice theme, as you can see.

In any case, that’s what’s under the hood of this site. All pages and posts are written in AsciiDoc dynamic markup, converted to HTML by the Asciidoctor rendering engine, built into a proper site by Jekyll static generator with a lightweight theme called Hyde giving the pages structure and style. Then served on GitHub Pages.

Now hosted on the fantastic Netlify continuous docs deployment platform!

I’ve been working with Jekyll and Asciidoctor for well over a year now, and I am confident that they are robust, pliable utilities that can solve a very wide range of technical documentation problems. This is especially true when you consider the broad range of Asciidoctor output.

In this blog, I will journal some of my technical experiments in documentation tooling, much of it around Asciidoctor and my own free and open source tool, LiquiDoc. All of this tooling is FOSS, and it’s all written in Ruby, which I started learning some months back in order to hack a complex docs build toolchains. Now I’m looking for new projects and challenges, which i hope to trace here.

Not that I’m hacking or extending it, the other major tool all of this depends on is Git.

If you’re a technical documentarian of any kind, consider checking out my book Codewriting. I’ve set up an RSS feed, and I’ll be posting links on my nascent Twitter account (@_codewriter) as soon as I get my shit together.