❭ Back to the index

Setup Jekyll, Asciidoctor and PlantUML with Github pagesJanuary 04, 2016

Introduction

I recently set up a new blog based on Jekyll, Asciidoctor and PlantUML, where the blog is hosted on gh-pages.

I run into some problem while setting the whole thing up so I will document my steps below.

Clone and prepare the Jekyll Asciidoctor Quickstart repository

  • Go to https://github.com/asciidoctor/jekyll-asciidoc-quickstart and follow the instructions on the page.

    We need to add a seperate step between Step 3 and 4 if you want to use the blog on your main github domain (http://<username>.github.io).

    • If you want to use the blog on the main github domain http://<username>.github.io as I did then github will use the master branch as the branch to serve the site from. Therefore you need to move all the files from the master branch into another branch:

    • Create a new branch where you write the articles

      git checkout -b develop

      and push it to the repository. Then you can continue with the steps outlined in the tutorial above.

  • After Travis build your site we can start to configure the Jekyll installation for the use of PlantUML.

    Edit your Gemfile to include the jekyll-plantuml and the asciidoctor-diagram gem (taken from https://github.com/asciidoctor/jekyll-asciidoc):

    source 'https://rubygems.org'

gem 'jekyll', '~> 2.5'
gem 'asciidoctor', '~> 1.5'
gem 'coderay', '1.1.0'
gem 'rake-jekyll', '~> 1.0'
gem 'jekyll-plantuml', '~> 1.1' (1)

group :jekyll_plugins do
  gem "jekyll-asciidoc"
  gem 'asciidoctor-diagram' (2)
end
    1 Here we add the plantuml dependency
    2 Advise Jekyll to render the diagrams

    This enables your Jekyll instance to render any PlantUML diagram as you can see here:

plantuml example

  • For Travis we need to add some configuration to the travis.yml file so it is able to render the diagrams and adds them to the pushed site.

    Edit the travis.yml to look like this:

language: ruby
rvm:
- 2.2.0
sudo: false
script: bundle exec jekyll build && bundle exec rake deploy (1)
addons:
  apt:
    packages:
    - graphviz (2)
env:
  global:
    secure: <yourToken>
1 In order to build and include the images correctly Jekyll needs to run twice, therefore we add one build step before the actual deploy.
2 Travis needs graphviz to render the images, luckily it is whitelisted in the container environment and we can require it here.

This should be all you need to configure to be able to render code diagrams in your blog. You can now start to change the design of the blog in general. On this site for example I used the github theme on http://themes.asciidoctor.org/preview/ and changed the layout a little bit.

Happy blogging!