Asciidoc and Friends

I started writing notes to myself, as options to develop online notes and such are getting larger everyday, and cool tools have been developed.

This is one of the those random documents that describes the text-based document formatting tools. Ironically, this is written in Markdown, as it was required by the underying static page creator framework Hugo.

Table of Contents

AsciiDoc

AsciiDoc ¹ is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs. AsciiDoc samples can be translated to many formats including HTML, PDF, EPUB, man page.

Asciidoctor

AsciiDoctor ² is a fast text processor & publishing toolchain for converting AsciiDoc to HTML5, DocBook and more.

Here is an example Asciidoc (sample.adoc) document:

= AsciiDoc is Writing Zen
Doc Writer <doc.writer@example.com>
:icons: font

_Zen_ is the *art* of writing `plain text` with http://asciidoc.org[AsciiDoc]

[TIP]

Use http://asciidoctor.org[Asciidoctor] for the best Asciidoc experience. footnote:[No to mention the best looking output!] Then icon:twitter[role=aqua] about it!

== Sample section

[square]
* item 1
* item 2

[source,ruby]
puts "Hello, world!"

and

$ asciidoctor sample.adoc

generates sample.html.

Asciidoctor-pdf

AsciiDoctor PDF ³ is a native PDF converter for AsciiDoc.

$ asciidoctor-pdf sample.adoc 

generates sample.pdf

Asciidoctor-fopub

fopub is a tool to convert DocBook (xml) to pdf.

It is a two-step process:

  1. Convert .adoc to .xml
$ asciidoctor -b docbook -d book -a data-uti! sample.adoc

generates sample.xml, and

  1. Convert .xml to .pdf
 $ fopub sample.xml

generates sample.pdf.

Finally…

Here is a slide deck promoting AsciiDoc ;-)


¹https://asciidoc.org/
²https://asciidoctor.org/
³https://Asciidoctor.org/docs/Asciidoctor-pdf/
https://github.com/Asciidoctor/Asciidoctor-fopub/