Asciidoctor

I like control. I like to control every last little bit of what I make; that way, if things don’t work, I know who to blame and I can solve the problem, because I have total control. The downside of having total control is that you have to do everything yourself. Explicitly. That’s a pile of work, so there’s a compromise to be made for the sake of efficiency: Enter Markdown and Content Management Systems.

Markdown was my first attempt to speed things up, and that was a mistake; just google why not to use markdown (oh, look, I already did it for you), and you’ll understand. By the time I learned the hard way, I was into the job a fair way, and didn’t want to start all over with a different system, which is when I found Asciidoc, and Asciidoctor. Great stuff. There’s a nice Asciidoctor-vs-Markdown page on their site as well, if you’re looking for a fair comparison (not a slagging match).

Whilst reading up on them, I found Antora , a great content management system; try it out by all means—​you might love it—​but it isn’t for me. Working with Antora UI just felt like patching a patch onto a patch until you decide to throw the old garment out and sew a new one…​ So, I’m using straight and simple Asciidoctor (I firmly believe it to be the superior 'markdown-like' solution)

I’m using make to make my life a little easier—​there’s a good tutorial here —and I’ve doctored the Asciidotor CSS a little and added my own navbar, as well as some patches to prevent the the body and links from sliding under said navbar.

If you’re interested; I’ve built a Zip archive of an 'empty' bare-bones version of this site, complete with Make-file and so on, it’s a good starting point if you need something like this. It’s my way of doing things, there may be—​probably are—​far better ways, but this is how I choose to do it, and I’ve left it here. For you. For free. Grab it if you like. Let me know what you think.

Static site template [2.2 MB]