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
  • slides

Installing Asciidoctor

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

Docker Image

See the Asciidoctor.org page for more details

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?

Examples, Tips, Tricks

Demo Time!

Headings, TOC, and Lists

Section heading are indicated with = sign up to five levels deep, not including the Document Title. Each section makes 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 be placed at the beginning of the document, on the left or right side of the document, or anywhere you want 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 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 a CSV file

[format="csv", options="header"]
|===
include::finances.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.

bat tux

Links

Web links can easily be added to a document. Just by typing them in, they will become a live link in the rendered document. If you want a name displayed for the link, add it in square brackets directly after the link, with no space before the opening bracket.

Please visit the http://calug.org website for more information.
Please visit the http://calug.org[CALUG] website for more information.

Please visit the http://calug.org website for more information.

Please visit the CALUG website for more information. <<<<

Links to local files may be created using the link: macro

link:finances.csv[The Finances File]

The Finances File

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, backend used, and other items.

References

← →