Jekyll Github Asciidoc Oh My
Having used Wordpress to host my blog for the last few years, I thought it was time to get in with the cool kids and instead host my blog on github pages, using Jekyll. As well as more control over its styling, using Jekyll also allows me to write and preview blog posts offline, and publish with simply a
I’ve also been reworking the Apache Isis documentation to Asciidoc (from a mix of Markdown and HTML), and wanted to be able to write blog posts in Asciidoc too. That introduces a slight issue: (at the time of writing at least) github doesn’t natively support Asciidoc. Thus, I need to use a CI job to convert the Asciidoc into vanilla .html, and then push to github.
Luckily there are others who have gone before me, and so with thanks to Paul Rayner, Evgeny Shepelyuk, Tobias Sjösten, John Ericksen and others, this blog is now hosted on github. A travis CI job does the jekyll processing and pushes to github. The only real bit of magic is to set up the authentication token so that travis has permission to perform the push.
That means my workflow is now as follows:
from the command line, run jekyll:
bundle exec jekyll serve
open up my browser at http://localhost:4000
write a new Asciidoc post in
_postsdirectory, and review in the browser
commit and push when happy :
git commit -am "new blog post" && git push
With respect to the source of this blog’s repo, a couple of points are worth further explanation:
the source Asciidoc is in the
jekyllbranch, while the published HTML is on the
This results in a git project history of two parallel never connecting branches; but then again, this is what github’s own gh-pages branches also do. (If you didn’t like this I suppose you could have two repos, one for the source Asciidoc and the other merely holding the published HTML).
jekyllbranch) tells Travis how to execute the CI job. Note that this references the
build.shfile. It also restricts travis to only process pushed to the
jekyllbranch; we don’t want travis to do anything when it pushes the published HTML to the
CNAMEfile tells github to map the github page to my own custom domain (danhaywood.com).
Anyway, if this approach to maintaining a blog appeals, then feel free to copy and adapt for yourself.