Building a simple docs site with asciidoctor and jekyll

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Building a simple docs site with asciidoctor and jekyll

joster
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]
Reply | Threaded
Open this post in threaded view
|

Re: Building a simple docs site with asciidoctor and jekyll

gour
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)?
Reply | Threaded
Open this post in threaded view
|

Re: Building a simple docs site with asciidoctor and jekyll

mojavelinux
Administrator
In reply to this post by joster


Asciidoctor has made my life much, much easier

\o/

 the css is (quite heavily) modified from the base asciidoctor stylesheet.

Excellent. We encourage that. The default stylesheet should help to get you up and running, but ultimately you want your docs to look like your docs. And you've done exactly that. Nice work!

I've added this entry to the "Who's Using Asciidoctor?" issue so that it makes its way onto the page on asciidoctor.org once it is setup.

-Dan

--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
Reply | Threaded
Open this post in threaded view
|

Re: Building a simple docs site with asciidoctor and jekyll

johncarl81
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