How to install ASCIIDoctor

From Ubuntu repositories

This is easy, but the ASCIIDoctor version and the default theme it uses is ancient:

$ sudo apt install asciidoctor

$ aptitude show asciidoctor
Package: asciidoctor
Version: 0.1.4-1

From Ruby Gems

This is a more updated version with an updated theme:

$ sudo gem install asciidoctor

$ gem list asciidoctor

*** LOCAL GEMS ***

asciidoctor (1.5.2)

How to center image caption in ASCIIDoctor

Problem

A caption to an image is provided in ASCIIDoctor document as follows:

.This is a caption
image::foo.png[align="center"]

However, the caption is aligned to the left by default.

Applying a text-center on it does not work:

[.text-center]
.This is a caption
image::foo.png[align="center"]

Solution

This problem has been discussed in this Github issue. The solution provided to add a few lines to imageblock in the stylesheet does not work. Instead, I changed the default behavior itself in the stylesheet to be center.

  • To do this first find out where gems are installed:
$ gem environment
  • Go to the INSTALLATION DIRECTORY output in the above command and to the subdirectory holds ASCIIDoctor stylesheets:
$ cd gems/asciidoctor-1.5.2/data/stylesheets/
  • Open the asciidoctor-default.css and find the place where for imageblock the text-align attribute is set to left and change that to center. For me, this was in line 177.

  • Rebuild your ASCIIDoctor document and the rendered HTML should have centered image caption.

Tried with: ASCIIDoctor 1.5.2, Ruby 2.1.0 and Ubuntu 14.04

LivePage extension for Chrome

The LivePage extension for Chrome is useful if you want to view a HTML page or file and want it to be refreshed as soon as it is updated. This can be useful if you are editing or producing the HTML file. For example, I use it to view the HTML file produced by compiling a ASCIIDoc or ASCIIDoctor file.

  • Open the local or internet webpage and click the LivePage icon. The page will be refreshed as soon as it is changed.

  • Note: If you want to refresh local HTML files, head to Chrome Extensions section, scroll down to LivePage and enable the Allow access to file URLs checkbox.

Tried with: LivePage 1.5.2, Chrome 40.0.2214.115 (64-bit) and Ubuntu 14.04

Vim-ASCIIDoc plugin

Vim-ASCIIDoc is a useful plugin for Vim if you frequently edit ASCIIDoc files.

Install

In addition, to the Vim-ASCIIDoc plugin, it also requires the installation of Vimple and Asif, two plugins by the same author.

Usage

  • Plugin sets the compiler by default to asciidoc.

  • If you want to use asciidoctor as compiler, use the command :compiler asciidoctor

  • If you want to set the default compiler, add this line to Vimrc:

https://gist.github.com/ashwin/51f47a0fd7c6508d5740

  • If you use asciidoctor as compiler, the plugin will keep complaining that it needs to know the themes directory for this compiler. To set the themes directory, I set this in my Vimrc:
  • Once the compiler is set correctly, you can build a ASCIIDoc file by typing :make

Tried with: Vim 7.4 and Ubuntu 14.04

How to enable syntax highlighting for ASCIIDoctor

Syntax highlighting of Python code by ASCIIDoctor
Syntax highlighting of Python code by ASCIIDoctor

Adding source code to ASCIIDoc documents is easy, as described here. ASCIIDoctor can be used to easily convert them to HTML5 documents using the html5 backend (which is the default). However, the source code is not rendered with syntax highlighting.

To enable syntax highlighting:

$ gem install coderay
  • Set CodeRay as the syntax highlighter, by adding this attribute at the top of your ASCIIDoc document:
:source-highlighter: coderay

Tried with: CodeRay 1.1.0, ASCIIDoctor 1.5.2 and Ubuntu 14.04