Working with AsciiDoc and Asciidoctor

Jared Morgan

What Will You Learn Today?

  • Commands and procedures you can follow to install Asciidoctor.

  • How to write in AsciiDoc using different tools and methods.

Install Asciidoctor on Linux

For RPM-based systems

$ sudo dnf install asciidoctor

For Debian-based systems

$ sudo apt-get install asciidoctor

Install Asciidoctor on Windows

  1. Load RubyInstaller site and download the installer.

  2. Once Ruby is installed, install Asciidoctor through the command line:

    $ gem install asciidoctor

Install Asciidoctor on Mac

Ruby is installed by default on Mac, but you need 1.9.2 at a minimum.

See Installing Asciidoctor on Mac OSX for different approaches to installing Asciidoctor on Mac.

How Do I Write in AsciiDoc

Ways you can write AsciiDoc documents:

  • Write in a text editor and preview in Chrome.

  • Write offline in GUI Editors such as Atom.io.

  • Write online directly in GitHub.

  • Write offline in GitHub, commit changes when online, render to Asciidoctor automatically using Travis CI.

Text Editor with Chrome Preview

You can use a Google Chrome extension called Asciidoctor.js Live Preview to render a local file in Asciidoctor.

  1. Open Chrome’s Web App Store.

  2. Search for "Asciidoctor".

  3. Install the Extension.

  4. Ensure you set the access to local files permission in chrome://extensions

Atom.io Editor

Atom Editor is a GUI Editor, which is compatible with Linux/Mac/Windows.

Get it at http://atom.io and install it.

AsciiDoc Live Preview

  1. Open Edit⇒Preferences⇒Packages

  2. Search for asciidoc-preview and Install.

  3. Alternativley , you can download the package from GitHub and add it to ~/.atom/packages.

  4. Open an AsciiDoc file in Atom.

  5. CTRL+SHIFT+A to show.

Atom Editor AsciiDoc Syntax Highlighting

  1. Open Edit⇒Preferences⇒Packages

  2. Search for language-asciidoc.

  3. Install it like asciidoc-preview

Edit AsciiDoc Directly On GitHub

If you store your docs on GitHub, you can use the site’s editor to write in AsciiDoc, and get a basic render of AsciiDoc text.

AsciiDoctor Forkables

A GitHub "Forkable" or "Fork-And-Go" is a repository hosted on GitHub that you can make a copy of as a base, then customize and extend it to your requirements.

The goal of a good forkable is to get you up and running with a technology quickly.

Let’s take a look at two that utilize Asciidoctor beautifully:

  • Jekyll AsciiDoc Quickstart

  • HubPress Blogging Platform

Jekyll AsciiDoc Quickstart

  • README.adoc.

  • Easy way to set up a static single doc site.

  • Uses Travis-CI to build and stage your guide.

  • Git-backed so you can write off-line.

  • Works great on tablets once set up on a PC.

  • Free.

Publishing JAQ to HTML

Publishing the Android Users Guide to HTML takes one short command:

$ asciidoctor -a skip-front-matter index.adoc

Publishing JAQ to PDF

See convert AsciiDoc to PDF for instructions on installing asciidoctor-pdf

Once the gem is installed, run the build command:

$ asciidoctor-pdf -a skip-front-matter index.adoc

HubPress Blogging Platform

  • README.adoc.

  • Blogging app using asciidoctor.js.

  • Deployed and hosted on GitHub.

  • Publishes blogs to the static GitHub Pages site.

  • Free.

What You’ve Learned

  • Ways you can view AsciiDoc content easily.

  • Ways you can install Asciidoctor on a variety of Operating Systems.

  • Ways you can get started quickly with AsciiDoc.

  • Ways you can publish AsciiDoc to different formats.

How You Can Contact Me