Building a simple docs site with asciidoctor and jekyll

This is just a big thank you to Dan and all of the very helpful people here. I'm the lone tech writer at a small, primarily open-source software company (http://advancedtelematic.com/en/ if you'd like to check us out on the web), and Asciidoctor has made my life much, much easier in the couple of months since I switched from a homebrewed system using Markdown + pandoc + various makefiles and shell scripts.

We just reached a milestone in one of our open source projects (a suite for doing over-the-air software updates on vehicles), and the documentation site is written entirely in asciidoc, rendered with asciidoctor. The site itself is built with jekyll and jekyll-asciidoc, and the css is (quite heavily) modified from the base asciidoctor stylesheet.

If anyone is interested, you can take a look at the docs site at http://advancedtelematic.github.io/rvi_sota_server/, and check out the sources in the /docs directory of the github project. [https://github.com/advancedtelematic/rvi_sota_server]

joster wrote

The site itself is built with jekyll and jekyll-asciidoc, and the css is (quite heavily) modified from the base asciidoctor stylesheet.

Have you considered to use Hugo static site generator which might be more appropriate for non-blog, iow. general web site and it also has support for using AsciiDoc(tor)?

Awesome work Joster... always great to see this technique in action.

To highlight an offering from Asciidoctor, we've used jekyll, jekyll-asciidoctor, asciidoctor and Travis to facilitate on the fly editing and rendering of Asciidoctor content via Travis CI, specifically targeting documentation centric websites.  The end result is automatically rendered content (Travis watches for changes, renders and publishes the site) deployed any time you push to master.  Also, this means that you can edit the content directly on Github via a web browser.  I love the ability to edit content quickly in the browser or accept a PR and have content automatically updated.

We put together a quickstart project recently to bootstrap this functionality called JAQ: https://github.com/asciidoctor/jekyll-asciidoc-quickstart

This project includes the default asciidoctor css along with foundation css to encourage some good design behavior.

I based both of my most popular project documentation sites off of JAQ:
Parceler
Transfuse

Here are the source projects:

https://github.com/johncarl81/parceler-site
https://github.com/johncarl81/transfuse-site

I'm curious if this technique would also work for your content.  If anything, maybe having the content published automatically via Travis may be of benefit.  Food for thought.

John