1. Convert
+-
+
-
+
Open a console
+
+ -
+
Switch to the directory that contains *.adoc documents
+
+ -
+
Call the Asciidoctor processor with the command
+
+
+ + | +
+ Convert example
+
+
+
+
+
+
+
+Please note, there is a asciidoctor in ./path + |
+
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 with different groups of people in different ways simultaneously within the same project 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
+-
+
-
+
the Chrome extension
+
+ -
+
or the Firefox add-on
+
+ -
+
or the Opera extension
+
+
Then you can see the AsciiDoc file rendered as HTML just by visiting it!
++
4.1. Installing the Chrome Extension
+-
+
-
+
Download asciidoctor-chrome-extension.nex
+
+ -
+
Open chrome://extensions
+
+ -
+
Drag’n’drop the
+.nex
file into the page to install
+
4.2. Installing the Firefox Extension
+-
+
-
+
Download asciidoctor-firefox-addon.xpi
+
+ -
+
Open the file with Firefox to install
+
+
4.3. Installing the Opera Extension
+-
+
-
+
Dowload asciidoctor-chrome-extension.nex
+
+ -
+
Open opera://extensions
+
+ -
+
Drag’n’drop the
+.nex
file into the page to install
+
That’s all folks! :-)
+