Asciidoctor is a fast text processor and publishing toolchain for converting AsciiDoc content to HTML5, DocBook 5, EPUB3, PDF and other formats. Asciidoctor is the leading implementation of the AsciiDoc syntax, first introduced and implemented in the Python-based AsciiDoc project.

1. Convert

  • Open a console

  • Switch to the directory that contains *.adoc documents

  • Call the Asciidoctor processor with the command

Convert example
docker run --rm -v $(pwd):/documents/ registry.vlabs.uniwa.gr:5080/swarmlab-asciidoctor asciidoctor --safe -b html5  -a theme=flask -a toc2 -a toc-placement=right -o ./path/to/FILENAME.html   ./path/from/FILENAME.adoc

Please note, there is a asciidoctor in ./path
Convert2html/pdf
pathname="$1" (1)
docker run --rm -v $PWD:/documents/  asciidoctor/docker-asciidoctor asciidoctor       --safe -b html5  -a theme=flask -a toc2 -o $pathname.html   $pathname (2)
docker run --rm -v $PWD:/documents/  asciidoctor/docker-asciidoctor asciidoctor-pdf   --safe -a toc  -o $pathname.pdf   $pathname (3)
1 The first argument from a command line can be found with the positional parameter $1.
2 See asciidoctor -b html5 options
3 See asciidoctor-pdf option

1.1. More options

More options

  • diagrams with asciidoctor-diagram options

  • presentation with asciidoctor-revealjs -a revealjsdir=https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.9.2 option

  • mathematical with asciidoctor-mathematical option

  • etc

2. Why AsciiDoc?

  • It is only TEXT. So you can "versioning" and collaborate More info

  • Standardized format

    • The formatting of Asciidoc is standardized so there is only one 'flavor' unlike in Markdown. The definitive user guide is here

  • Asciidoctor can convert directly to HTML or DocBook.

AsciiDoc is about being able to focus on expressing your ideas, writing with ease and passing on knowledge without the distraction of complex applications or angle brackets.

AsciiDoc works because:

  • It’s readable

  • It’s concise

  • It’s comprehensive

  • It’s extensible

  • It produces beautiful output (HTML, DocBook, PDF, ePub and more)

AsciiDoc is easy to write and easy to read (in raw form). It’s also easy to proof and edit. After all, it’s plain text, just like that familiar e-mail.

Best of all, it only requires a text editor to read or write.

3. AsciiDoc vs Markdown

The defacto lightweight markup language is Markdown. (At least, that’s what you call it at first). The main advantage of Markdown lies in its primitive syntax: its manual and cheatsheet are one and the same. But this advantage is also its greatest weakness.

As soon as authors need something slightly more complex than basic prose (e.g., tables, cross references, footnotes, embedded YouTube videos, etc.), they find themselves resorting to embedded HTML or seeking out more feature-rich implementations. Markdown has become a maze of different implementations, termed “flavors”, which make a universal definition evasive.

The IETF has declared “there is no such thing as "invalid" Markdown.” See This Is Markdown! Or: Markup and Its Discontents.

Here’s how the story inevitably goes.

  • You start out with Markdown.

  • Then it’s Markdown + X.

  • Then Markdown + X + Y.

  • And down the rabbit hole you go.

What’s worse, X and Y often require you to sprinkle in HTML, unnecessarily coupling content with presentation and wrecking portability. Your instinct to choose Markdown is good. There are just better options.

4. Setup live preview Using a web browser

All you need to preview an AsciiDoc document in a web browser is to install

Then you can see the AsciiDoc file rendered as HTML just by visiting it!

Live Preview

Swarmlab

4.1. Installing the Chrome Extension

  1. Download asciidoctor-chrome-extension.nex

  2. Open chrome://extensions

  3. Drag’n’drop the .nex file into the page to install

4.2. Installing the Firefox Extension

  1. Download asciidoctor-firefox-addon.xpi

  2. Open the file with Firefox to install

4.3. Installing the Opera Extension

  1. Dowload asciidoctor-chrome-extension.nex

  2. Open opera://extensions

  3. Drag’n’drop the .nex file into the page to install

5. Install Docker

Docker is a set of platform as a service (PaaS) products that use OS-level virtualization to deliver software in packages called containers.

Containers are isolated from one another and bundle their own software, libraries and configuration files; they can communicate with each other through well-defined channels

installation

That’s all folks! :-)