gem install asciidoctor
Standard file extensions
.adoc
, .asciidoc
, .asc
(Supported by Github).ad
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:
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
A text editor
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:
Examples, Tips, Tricks
Demo Time!
Asciidoc does Slides
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
Three
* One
* Two
* Three
** Three Sub 1
Three
Paragraphs are just blocks of text separated by blank lines.
Write your paragraph sentences on separate lines.
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 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[]
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[]
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://unallocatedspace.org website for more information.
Please visit the http://unallocatedspace.org[Unallocated Space] website for more information.
Please visit the http://unallocatedspace.org website for more information.
Please visit the Unallocated Space website for more information.
Links to local files may be created using the link:
macro
link:financesdemo.csv[The Finances File]
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.
: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.
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:
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.
// 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 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 |
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.