Introduction to Asciidoc(tor)

Chuck Frain
chuck@chuckfrain.net

What We’ll Discuss

  • What is Asciidcoc?
  • What is Asciidoctor?
  • Writing Tools
  • Writing Tips and Tricks for Asciidoc

What is Asciidoc?

  • Asciidoc is a markup language
  • Started life in the Python project
  • It is readable as ascii text
  • It is extensible
  • Works well in Git and other versioning tools
  • Allows for include files
  • Standard file extensions

    • .adoc, .asciidoc, .asc (Supported by Github)
    • .ad

What is Asciidoctor?

Asciidoctor is a post processor for the Asciidoc markup language

It converts Asciidoc documents to other formats, directly or indirectly, such as those in this [incomplete] list:

  • HTML(5)
  • PDF
  • Docbook
  • manpage
  • mobi
  • epub3

Installing Asciidoctor

gem install asciidoctor
dnf install asciidoctor -y
apt-get install asciidoctor -y

Docker Image

See the Asciidoctor.org page for more details

Using Asciidoctor

asciidoctor asciidoc_file.adoc

The above command generates asciidoc_file.html and embeds the CSS

asciidoctor -a linkcss asciidoc_file.adoc

The above command generates asciidoc_file.html and asciidoctor.css files

asciidoctor -b docbook asciidoc_file.adoc

The above command generates a docbook asciidoc_file.xml file

What tools are needed to write in Asciidoc?

A text editor

  • Vim
  • Emacs
  • Notepad++
  • Atom
  • Sublime

As long as the editor saves in ascii text (i.e a .docx file will not work) you can use it

It really is just text!

Nice to have:

  • Syntax Highlighter
  • Preview plugin for your browser
  • Preview plugin for your editor (if supported)

What does an Asciidoc doc look like?

asciidoctor presentation uas 54029
Figure 1. Asciidoc source vs rendered

Examples, Tips, Tricks

Demo Time!

Before moving on…​

one more thing

Asciidoc does Slides

Headings, TOC, and Lists

Section heading are indicated with = sign up to five levels deep, not including the Document Title. Each section can make up an entry in the Table of Contents(TOC). The TOC has options to include down to a certain number of levels, 3 by default. The TOC can exclude certain headings using the [discreet] tag. The TOC can be placed at the beginning of the document, on the left or right side of the document, or anywhere within the document depending on the option selected.

= Level 0 (Document Title)
== Level 1
=== Level 2
==== Level 3
===== Level 4
====== Level 5

Lists can be created as an ordered or unordered list up to five levels deep. A period (.) at the beginning indicates an ordered list. An asterisk (*) is used for unordered list.

. One
. Two
. Three
.. Three Sub 1
  1. One
  2. Two
  3. Three

    1. Three Sub 1
* One
* Two
* Three
** Three Sub 1
  • One
  • Two
  • Three

    • Three Sub 1

Paragraphs

Paragraphs are just blocks of text separated by blank lines.

Write your paragraph sentences on separate lines.

  • Editing single lines and moving sentences around is easier.
  • It is easier to see when you have long sentences.
  • Each sentence becomes a string.
  • This will help when you’re versioning.
  • When diffing changes, you don’t get massive blocks of text with a one letter change.
  • If there are errors when generating a document, finding the line in a paragraph that is causing it is easier. (This is an edge case)

Tables

Create tables within the document

[options="header", grid=rows]
|===
|Cell in C1R1 |Cell in C2R1
|Cell in C1R2 |Cell in C2R2
|Cell in C1R3 |Cell in C2R3
|===
Cell in C1R1 Cell in C2R1

Cell in C1R2

Cell in C2R2

Cell in C1R3

Cell in C2R3

Create a table by including an external CSV file

[format="csv", options="header"]
|===
include::financesdemo.csv[] (1)
|===
1 The CSV file to create the table from
Month Income Spending

Jan

$4500

$679

Feb

$3300

$4567

Mar

$9900

$2345

Images

Images can be added to a document using the image::<filename.jpg>[] attribute.

image::bat-tux.jpg[]
image::http://www.picgifs.com/graphics/t/tux/graphics-tux-850120.gif[]
bat tux
graphics tux 850120

The images are stored, by default, in the images directory relative to the document. This can be modified by using the :imagesdir: directive and specifying the desired relative path.

The screenshot attribute can be used when the asciidoc-screenshot extension is installed. The following code example in a document will take a screenshot of the Google France lading page when the document is rendered.

[screenshot, url=http://google.fr, name=google]
Google Landing page

Using the asciidoc-image-helper plugin for the Atom editor allows for pasting images from the clipboard into the current document. When pasted, the image file is created in the images directory (by default) with the name of the document and a random hash as the filename. The image:: attribute with this filename is created within the doc.

image::asciidoctor_presentation_uas-26aa6.png[]

Attributes

Use attributes where they make sense.

Attributes can be used and thought of as variables. Attributes can be stored in separate files for ease of reuse and included in a master index file.

  • Product and Company names
  • Websites
  • Repeated, difficult to type text
  • Attributes can be nested:
:calug: Columbia Area Linux User Group
:prod: Linux
:lead: mailto:chuck@chuckfrain.net[Chuck Frain]
:uri-calist: http://lists.unknownlamer.org
:uri-archive: {uri-calist}/pipermail/calug
:uri-mar16mail: {uri-archive}/2016-March
:uri-mar16thread: {uri-mar16mail}/thread.html
:uri-mar16list: {uri-mar16mail}/list.html
Welcome to {calug}, a {prod} and free software group.
If you want to give a presentation, please contact {lead}.
The March mailing list is archived by {uri-mar16thread}[thread] or list {uri-mar16list}.

Welcome to Columbia Area Linux User Group, a Linux and free software group. If you want to give a presentation, please contact Chuck Frain. The March mailing list is archived by thread or list http://lists.unknownlamer.org/pipermail/calug/2016-March/list.html.

Includes

include::somefile.txt[]

The include macro will include the file indicated to the generated document. This feature can be used in many different ways, among them:

  • Company name and contact information
  • About Us text
  • Legal text
  • Copyright information
  • CSV files for tables
  • Code blocks
  • Asciidoc Chapters

Admonitions

Admonitions such as NOTE, TIP, WARNING, CAUTION, and IMPORTANT blocks can be created simply by using the name in all caps followed by a colon at the beginning of a line. The rest of the paragraph text will be included.

Comment your documentation

Comment your documentation.

// Asciidoc supports single line comments using a double slash at the beginning of the line.

////
A block of text may be commented using four slashes on the line before and after the text to be commented out.
Using comments allows you to leave thoughts for yourself or co-writers about the text, future features that are not ready to be published, or around text that is undecided.
////

Comments are not passed to processed output.

Callouts

Callouts in your examples

prices = {'apple': 0.40, 'banana': 0.50} <1>
my_purchase = {
    'apple': 1,
    'banana': 6} <2>
grocery_bill = sum(prices[fruit] * my_purchase[fruit]
                   for fruit in my_purchase) <3>
print 'I owe the grocer $%.2f' % grocery_bill <4>

<1> The price of fruit
<2> The amount of each fruit I'm purchasing
<3> Calcualting the bill for my fruit purchase
<4> Prints the cost of my fruit in a friendly way
prices = {'apple': 0.40, 'banana': 0.50} (1)
my_purchase = {
    'apple': 1,
    'banana': 6} (2)
grocery_bill = sum(prices[fruit] * my_purchase[fruit]
                   for fruit in my_purchase) (3)
print 'I owe the grocer $%.2f' % grocery_bill (4)
1 The price of fruit
2 The amount of each fruit I’m purchasing
3 Calcualting the bill for my fruit purchase
4 Prints the cost of my fruit in a friendly way

Conditional Blocks

ifdef::[]
ifndef::[]
ifeval::[]

endif::[]

Conditional text can be used either by the existence or not of an attribute for the output.

Conditional text can also be evaluated based on evaluating conditions like section number levels, output file name, the backend used, and other items.

References

uas final
Figure 2. UAS Presentation link on Github