Article

Asciidoctor on OpenShift

 

May 12, 2015
DevOpsKubernetes
Samuel Mendenhall

Asciidoctor encompasses and builds an ecosystem around Asciidoc for writing documentation, and well, writing anything.   If you want to host your own blog, documentation site, book, ect.., Asciidoctor would be an excellent choice.  If you want to do that in OpenShift, that is what I'm going to help you with.

Getting Started

Create a Sinatra ruby gear or on the command line.

rhc app create mydocs sinatra ruby-2.0

The current sinatra-example is geared for ruby 1.9 current, https://github.com/openshift/. It could be modified to work with 2.0 but I will focus on 1.9 here.

rhc app create mydocs ruby-1.9 --from-code https://github.com/openshift/sinatra-example.git

You may or may not need to clone the project, it should auto-clone it unless there was a timeout.

rhc git-clone mydocs
cd mydocs

Set your environment up so the bundler won't install dev dependencies.

rhc env set BUNDLE_WITHOUT=development -a mydocs

This gives us a base Sinatra project to work with. Now let's add Asciidoctor to the mix.

Configure Ruby for Asciidoctor

Add the Asciidoctor gem and development gems to bundler and bundle. Your Gemfile should look like:

source 'https://rubygems.org'

gem 'sinatra'
gem 'asciidoctor'

group :development do
    gem 'guard'
    gem 'guard-shell'
    gem 'guard-livereload'
end

Now Install those new gems, this will also trigger a new bundle install when you push since the Gemfile.lock will change.

bundle install

Write an Asciidoc file

Create a folder for your Asciidoc files, let's call it adocs.

mkdir adocs

Create an adocs/index.adoc, open it up and paste in:

= Introduction
:linkcss:
:toc: left

Welcome to my documentation!

== Heading 1

=== Sub Heading 1

== Heading 2

=== Sub Heading 1

=== Sub Heading 2

Development and LiveReload

Create a Guardfile in the project root. The :safe => :unsafe is for the injection of asciidoctor.css into the html. This Guardfile will watch for changes to the index.adoc and compile it to the public dir.

require 'asciidoctor'

guard 'shell' do
  watch(/^adocs/index.adoc$/) {|m|
  Asciidoctor.convert_file(m[0], :to_dir => "public", :safe => :unsafe)
}
end

guard 'livereload' do
  watch(%r{^public/.+.(css|js|html)$})
end

Add public/index.html and public/asciidoctor.css to .gitignore as Asciidoctor will be invoked on push.  The benefit to this setup is your generated html will not pollute git, it will be generated on push.

echo "public/index.html" >> .gitignore
echo "public/asciidoctor.css" >> .gitignore

Install the LiveReload browser extension then guard start http://asciidoctor.org/docs/editing-asciidoc-with-live-preview/

guard start

Click on the Live Reload icon in the browser, in the Guard console you should see:

[1] guard(main)> 13:30:31 - INFO - Browser connected.

Now you can live edit the index.adoc and see updates in the browser. You will need to navigate to the file in your browser. In my case I went to the url: file:///Users/smendenh/Projects/mydocs/public/index.html

Production

Add a .openshift/action_hooks/build file which will be responsible for invoking Asciidoctor to generate the html.

mkdir -p .openshift/action_hooks
vim .openshift/action_hooks/build

#!/bin/bash

pushd $OPENSHIFT_REPO_DIR > /dev/null
bundle install --path ./vendor/bundle --without development
bundle exec ruby -C${OPENSHIFT_REPO_DIR} -rasciidoctor -e "Asciidoctor.convert_file('adocs/index.adoc', :to_dir => 'public', :safe => :unsafe)"
popd > /dev/null

Test it out!

Edit the adocs/index.adoc file, change anything.

git commit -a -m "Simple update"
git push

Wait for the push to finish then hit the openshift url for your gear in the browser and see your changes.

Other ideas for Asciidoctor on OpenShift

You can use Asciidoctor in many languages, be it Java, Ruby, Javascript, ect...   Hooking in Asciidoctor to the Sinatra gear was simple and straight forward, the documentation on the Asciidoctor.org site was a fantastic help.  There is around a 30 second delay in git push, that is minor, but if you wanted an even faster means of hosting an Asciidoctor based OpenShift gear you could use the Nginx gear and push the generated html.  I've done that, and it is incredibly fast to push to and update.

Last updated: May 29, 2023