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.
****
== Convert
- Open a console
- Switch to the directory that contains *.adoc documents
- Call the Asciidoctor processor with the command
.Convert example
[NOTE]
====
[source,bash]
----
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
[source,bash]
----
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
=== 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
** The formatting of Asciidoc is standardized so there is only one 'flavor' unlike in Markdown. The definitive user guide is http://asciidoctor.org/docs/asciidoc-writers-guide/[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.
== 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.
[NOTE]
====
The IETF has declared “there is no such thing as "invalid" Markdown.” https://tools.ietf.org/html/rfc7763#section-1.1[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.*
== Setup live preview Using a web browser
All you need to preview an AsciiDoc document in a web browser is to install
- the https://chrome.google.com/webstore/detail/asciidoctorjs-live-previe/iaalpfgpbocpdfblpnhhgllgbdbchmia[Chrome extension]
- or the https://addons.mozilla.org/en-US/firefox/addon/asciidoctorjs-live-preview[Firefox add-on]
- or the https://addons.opera.com/fr/extensions/details/asciidoctorjs-live-preview[Opera extension]
Then you can see the AsciiDoc file rendered as HTML just by visiting it!
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
