Jekyll and Asciidoc

I wished to create a blog that would be easy enough to maintain that I would actually take the time to contribute to it. In order for that to happen, I decided that it would require the following:

This has led me, after much musing, to a combination of Jekyll, Asciidoc, and GitHub Pages. The blog you see before you today is a result of those choices.

Git is my VCS of choice, and has been for almost a decade. Pretty much a no-brainer.

I decided that I would use Github Pages for hosting. The pro’s for this choice were:

I have, over the years, had web sites which were maintained with Django, Wordpress, and other back-ends, but every one of them falls behind in security patches, plugin versions, etc. I wanted something that I could leave for months at a time, if necessary, and then just pick up my text editor, and publish, without having to worry about managing any code. Github Pages is always on, and I don’t need to manage anything except DNS records, and my Git repository.

Nice.

This decision was borne out of the Github Pages decision. Jekyll is a static site generator written in Ruby, and supported by Github Pages natively.

Unfortunately my next decision, to use Asciidoc, required that I not use the built-in integration. Not to worry, though. I found a workaround that still meets my goal to have automatic publishing based on a git push, without requiring any of my own infrastructure.

This is where I stray from the beaten path. Many people like to use Markdown (or one of it’s patchwork offspring). I have nothing against Markdown, execpt for the fact that there really isn’t a markdown. CommonMark is promising, but not widely supported. Also, it doesn’t have nearly the power of Asciidoc for other tasks, like writing comprehensive technical documentation, one of my other use-cases. One of the drawbacks to learning a text-based markup language like Markdown, ReStructured Text, and others is that each dialect is similar enough to be stored in the same area of the brain, but has enough differences that they often get muddled up (in my head, anyway). So you end up using a Markdown idiom when writing ReST, etc.

By deciding on one language to rule them all, I am forsaking all others (not really, since other people still use them, and I don’t live in my own world). At least, I am hopeful that by focusing on Asciidoc as my primary dialect, I will not make as many mistakes when I am using it.

As I chose Asciidoc, I could not use the Github integration for Jekyll, as they don’t support the Asciidoc plugin. I’m not sure why, and there are a number of people who, I am sure, have asked them to reconsider, but for now, that means that I need an external way of building my site. Fortunately, there are some great tutorials on how to use Travis to execute builds that are triggered by Github Hooks. The one I followed is this one by Evgeny Shepelyuk.

What the workflow looks like when all this is glued together is:

Clone Github Repo → Edit in IntelliJ IDEA (or whatever I have handy) → Push to Github → Hook fired to Travis → Travis executes the Jekyll build and pushes to the Github master repo → Profit.

I will be documenting this process in more detail, for those who would like to replicate my setup. For now, however, there are a great many tutorials online that can talk about the individual steps.

Also, I didn’t discuss anything about themes or artwork. That’s probably an entire topic on its own.

Until next time…​

-Sage