Asciidoc

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 use markdown", and you’ll understand. I was into the job a fair way, and didn’t want to start all over with a different system, when I found Asciidoc, and Asciidoctor. Great stuff. I read up on them and found Antora, a great content management system, but the problem with using a tool designed by someone else is that they are not you. You have a different idea than they, and when you’re me, that’s a problem: I want control.

I tried messing with the Antora UI and it’s just like patching a patch onto a patch until you decide to throw the old garment out and sew a new one…​

I’m still using Asciidoc and Asciidoctor (I firmly believe it to be the superior 'markdown-like' solution), but I’m not using Antora; I just can’t live with losing that much control. I’m using make and make-files to make my life easier, and I’ve doctored the Asciidotor CSS a little and added my own navbar.

This is where the compromise really hurts a little; I have to inject the navbar through an 'include' in Asciidoctor. I have patched a couple of hacks into the CSS to get link targets to show up below the navbar and not under it, but there’s no easy selector to do this with the 'back-link' of a footnote, so, when returning to the reference after visiting it’s footnote, you’ll have to scroll up a little…​ I guess I can live with that for now, but I’m so anal that it will probably drive me bonkers soon and I’ll rewrite the whole documentation from scratch, hardcoded. Screw this. :-(