AsciiDoc For Complete Beginners

asciidoc

Guido Kroon

  • 👨‍💼 Information Security Manager

  • 👨‍💻 Using Git myself, at home and at work

  • 🌐 Open source

  • 🇸🇪 Talar lite svenska

My Corporate Keys

In case you ever wish to verify my signatures, or grant me access to any systems 👨‍💻

PGP fingerprint

26D3 D565 A520 CC89 4E45
7D0F 5922 172F 920C 075A

SSH public key

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICTtufd+r+Loakaa7Nj1bgbsthk0EPYeExak02KAFLNm

What Is AsciiDoc?

  • A lightweight markup language

  • Plain-text writing format for authoring notes, articles, reports, documentation, books, ebooks, web pages, slide decks, blog posts, man pages and more

  • Much more powerful than Markdown

  • Much more simpler than LaTeX

  • Originally developed by Stuart Rackham

Why Would We Need AsciiDoc?

  • Allows to focus more on actual writing

  • Avoids being distracted by complex word processors or finicky WYSIWYG editors

  • Writers should focus on writing, not drawing.

  • The main reason academics often turn to LaTeX, and developers often turn to Markdown.

What’s Wrong With M$ Word?

Perpetual distraction by trivialities, such as:

  • Font families, margins, line spacings

  • Table column and row widths

  • Picture and object placings

  • Pasting text from another source also copies different font family, size, colour…​

Word processors are the REAL writer’s block!

A Short LaTeX Example

  • Created by Leslie Lamport

  • Taking Donald Knuth’s TeX one step further

\documentclass{article}
\begin{document}
\section*{Lorem Ipsum}
Ch\'erie, \c{c}a ne me pla\^\i t pas! % comment \b
G\"otterd\"ammerung~45\%=34.
$$
    \int\limits_{0}^{\pi}\frac{4}{x-7}=3
$$
\end{document}

To be honest, I actually love LaTeX!

A Short Markdown Example

# Hello world

you can write text [with links](http://example.com) inline or
[link references][1].

* one _thing_ has *em*phasis
* two __things__ are **bold**

[1]: http://example.com

It is brilliant for taking notes!

An Example Asciidoc Pentest Report

How Can Asciidoc Help Pentesters?

  • It helps pentesters focus on writing observations

  • Predictable, simple and clean human readable plain-text

  • Time wasted during reporting is time wasted for pentesting

Compared To "Other" Systems (1/2)

  • No messing around with a dumb WYSIWYG editor

  • No manual debugging the underlying HTML

  • No downtime, being dependant on a running server preventing you from saving your hard work

Compared To "Other" Systems (2/2)

  • No losing your hard work when a colleague accidentally overwrites the same observation you’ve both been working on

  • Automatic substitution of known information, e.g. client names

How To Learn Asciidoc?

learn asciidoc

Getting Started

Asciidoctor

  • The de facto tool to render AsciiDoc

  • Sadly written in Ruby, but hey…​

  • Several extensions to render PDFs, presentations, diagrams, and much, much more

  • Maintained by Dan Allen, project lead

Installing AsciiDoc (1/2)

On Gentoo-based systems:

$ sudo emerge dev-ruby/asciidoctor
$ sudo layman -a 0bs1d1an # Yes, my own overlay :-D
$ sudo emerge dev-ruby/asciidoctor-pdf

On Arch-based systems:

$ sudo pacman -S --needed asciidoctor
$ sudo pacman -S --needed asciidoctor-pdf
unix beard

Installing AsciiDoc (2/2)

On Debian-based systems:

$ sudo apt install asciidoctor
$ sudo apt install asciidoctor-pdf

On RHEL-based systems:

$ sudo dnf install asciidoctor
$ sudo dnf install asciidoctor-pdf
unix beard

Paragraphs

Paragraphs don't require any special markup in AsciiDoc.
A paragraph is just one or more lines of consecutive text.

To begin a new paragraph, separate by at least one line.
Newlines within a paragraph are not displayed.

Result:

Paragraphs don’t require any special markup in AsciiDoc. A paragraph is just one or more lines of consecutive text.

To begin a new paragraph, separate it by at least one blank line. Newlines within a paragraph are not displayed.

Formatting

bold *constrained* & **un**constrained

italic _constrained_ & __un__constrained

bold italic *_constrained_* & **__un__**constrained

monospace `constrained` & ``un``constrained

Result:

bold constrained & unconstrained

italic constrained & unconstrained

bold italic constrained & unconstrained

monospace constrained & unconstrained

Headers

= Document Title (Level 0)

== Level 1 Section Title

=== Level 2 Section Title

==== Level 3 Section Title

===== Level 4 Section Title

== Another Level 1 Section Title

Including Files

= Hello World

This is documentation for project X.

include::basics.adoc[]

include::installation.adoc[]

include::example.adoc[]

Forcing Breaks

Rubies are red, +
Topazes are blue.

[%hardbreaks]
Ruby is red.
Java is black.

Result:

Rubies are red,
Pythons are green.

Ruby is red.
Python is green.

Page Breaks

<<<

Unordered Lists

* J.R.R. Tolkien
* Ursela K. Le Guin
* Arthur Conan Doyle

Result:

  • J.R.R. Tolkien

  • Ursela K. Le Guin

  • Arthur Conan Doyle

Nested Unordered Lists

* Europe
** Finland
*** Rovaniemi

Result:

  • Europe

    • Finland

      • Rovaniemi

Ordered Lists

. Morning
. Afternoon
. Evening

Result:

  1. Morning

  2. Afternoon

  3. Evening

Nested Ordered Lists

. Main
.. Sub
... Subsub

Result:

  1. Main

    1. Sub

      1. Subsub

Links

https://asciidoctor.org - automatic!

https://asciidoctor.org[Asciidoctor]

https://github.com/asciidoctor[Asciidoctor @ *GitHub*]

Result:

https://asciidoctor.org - automatic!

Asciidoctor

Asciidoctor @ GitHub

Videos

video::video_file.mp4[]

video::video_file.mp4[width=640, start=60, end=140, options=a
utoplay]

video::dQw4w9WgXcQ[youtube]

Tables

|===
|Name of Column 1 |Name of Column 2

|Cell in column 1, row 1
|Cell in column 2, row 1

|Cell in column 1, row 2
|Cell in column 2, row 2
|===
Name of Column 1Name of Column 2

Cell in column 1, row 1

Cell in column 2, row 1

Cell in column 1, row 2

Cell in column 2, row 2

Attributes And Substitutions

:url-home: https://asciidoctor.org
:link-docs: https://asciidoctor.org/docs[documentation]

Check out {url-home}[Asciidoctor]!

Be sure to read the {link-docs} too!

Result:

Check out Asciidoctor!

Be sure to read the documentation too!

Table Of Contents (ToC)

= My awesome article
Larry the Cow <larry@gentoo.org>
v1.0, 2019-10-09
:toc:

Drafting Your First Document

$ nvim document.adoc
:author: Larry the Cow
:email: larry@gentoo.org
:version: v1.0
:date: 2019-10-09

= Hello World
:doctype: book
{author} {email}
{version}, {date}

My name is {author}. In my spare time I enjoy:

* Eating grass
* Compiling Gentoo ebuilds

Generating Your First HTML Document

To generate your document in HTML:

$ asciidoctor document.adoc

Generating Your First PDF Document

To generate your document in PDF:

$ asciidoctor-pdf document.adoc

Exercises

Practise your new skills

Create Your First Document

  • Play around with headers, lists, tables, links, images, videos

  • Try highlighting source code, substituting text

  • Add a table of contents, bibliography, footnotes

  • Convert to HTML with asciidoctor

  • Convert to PDF with asciidoctor-pdf

Need A Hint?

  1. AsciiDoc Syntax Quick Reference

  2. AsciiDoc Writer’s Guide

  3. Asciidoctor User Manual