Table Of Contents

AsciiDoc(tor): Yo Dawg!

2024-04-02

1. Intro

Okay, let’s do it.

Testing include::<path>[] command
[source,config]
----
include::/home/hos/dev/hossein-lap/void-packages/etc/xbps.d/repos-remote.conf[]
----
Output
# voidlinux remote repositories (glibc)
repository=https://repo-default.voidlinux.org/current/bootstrap
repository=https://repo-default.voidlinux.org/current
repository=https://repo-default.voidlinux.org/current/nonfree
repository=https://repo-default.voidlinux.org/current/debug

2. Lists

2.1. Unordered lists

* level 1
** level 2
*** level 3
**** level 4
***** level 5
* level 1
Output

  • level 1

    • level 2

      • level 3

        • level 4

          • level 5

  • level 1

2.2. Ordered lists

. level 1
.. level 2
... level 3
.... level 4
..... level 5
. level 1
Output

  1. level 1

    1. level 2

      1. level 3

        1. level 4

          1. level 5

  2. level 1

2.3. TODO lists

- [*] checked
- [x] also checked
- [ ] not checked
- normal list item
Output

  • checked

  • also checked

  • not checked

  • normal list item

2.4. Separating lists

. Apples
. Oranges

//-

. Walnuts
. Almonds
Output

  1. Apples

  2. Oranges

  1. Walnuts

  2. Almonds

3. Definitions

3.1. Normal definition list

first term:: definition of first term
section term:: definition of second term
Output
first term

definition of first term

section term

definition of second term

3.2. Horizontal definition list

[horizontal]
first term:: definition of first term
section term:: definition of second term
Output
first term

definition of first term
section term

definition of second term

3.3. Multi-line definition list

first term::
definition of first term
section term::
definition of second term
Output
first term

definition of first term

section term

definition of second term

3.4. Q&A

[qanda]
What is Asciidoctor?::
An implementation of the AsciiDoc processor in Ruby.
What is the answer to the Ultimate Question?:: 42
Output

  1. What is Asciidoctor?

    An implementation of the AsciiDoc processor in Ruby.

  2. What is the answer to the Ultimate Question?

    42

3.5. Mixed

Operating Systems::
    Linux:::
        . Fedora
            * Desktop
        . Ubuntu
            * Desktop
            * Server
    BSD:::
        . FreeBSD
        . NetBSD
Cloud Providers::
    PaaS:::
        . OpenShift
        . CloudBees
    IaaS:::
        . Amazon EC2
        . Rackspace
Output
Operating Systems
Linux

  1. Fedora

    • Desktop

  2. Ubuntu

    • Desktop

    • Server

BSD

  1. FreeBSD

  2. NetBSD

Cloud Providers
PaaS

  1. OpenShift

  2. CloudBees

IaaS

  1. Amazon EC2

  2. Rackspace

Note that the indentation is optional

3.6. Complex content in outline lists

* Every list item has at least one paragraph of content,
  which may be wrapped, even using a hanging indent.
+
Additional paragraphs or blocks are adjoined by putting
a list continuation on a line adjacent to both blocks.
+
list continuation:: a plus sign (`{plus}`) on a line by itself

* A literal paragraph does not require a list continuation.

 $ gem install asciidoctor

* AsciiDoc lists may contain any complex content.
+
[cols="2", options="header"]
|===
|Application
|Language
|AsciiDoc
|Python
|Asciidoctor
|Ruby
|===
Output

  • Every list item has at least one paragraph of content, which may be wrapped, even using a hanging indent.

    Additional paragraphs or blocks are adjoined by putting a list continuation on a line adjacent to both blocks.

    list continuation

    a plus sign (+) on a line by itself

  • A literal paragraph does not require a list continuation.

    $ gem install asciidoctor

  • AsciiDoc lists may contain any complex content.

    Application Language

    AsciiDoc

    Python

    Asciidoctor

    Ruby

4. Links

4.1. External

http://asciidoctor.org - automatic!

http://asciidoctor.org[Asciidoctor]

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

http://asciidoctor.org - automatic!

Asciidoctor

Asciidoctor @ GitHub

4.2. Relative

link:test.adoc[Docs]
Output

Docs

4.3. Email and IRC

devel@discuss.arquillian.org

mailto:devel@discuss.arquillian.org[Discuss Arquillian]

mailto:devel-join@discuss.arquillian.org[Subscribe, Subscribe me, I want to join!]

irc://irc.freenode.org/#asciidoctor
Output

devel@discuss.arquillian.org

Discuss Arquillian

Subscribe

irc://irc.freenode.org/#asciidoctor

4.4. Inline anchors

[[bookmark-a]]Inline anchors make arbitrary content referenceable.

anchor:bookmark-b[]Use a cross reference to link to this location.
Output

Inline anchors make arbitrary content referenceable.

Use a cross reference to link to this location.

4.5. Internal cross references

See <<paragraphs>> to learn how to write paragraphs.

Learn how to organize the document into <<section-titles,sections>>.
Output

See [paragraphs] to learn how to write paragraphs.

Learn how to organize the document into sections.

4.6. Images

image::/images/asciidoc/rose.png[]

image::/images/asciidoc/rose.png[Rose]

[[img-sunset]]

image::/images/asciidoc/rose.png[caption="Figure 1: ", title="A rose", alt="Rose", width="300", height="200", link="http://www.flickr.com/photos/javh/5448336655"]

image::http://asciidoctor.org/images/octocat.jpg[GitHub mascot]
Output
rose
Rose
Rose
Figure 1: A rose
GitHub mascot

5. Admonition paragraph

5.1. NOTE

NOTE: This is a NOTE!
Output
This is a NOTE!

5.2. TIP

TIP: This is a TIP!
Output
This is a TIP!

5.3. WARNING

WARNING: This is a WARNING!
Output
This is a WARNING!

5.4. CAUTION

CAUTION: This is a CAUTION!
Output
This is a CAUTION!

5.5. IMPORTANT

IMPORTANT: This is a IMPORTANT!
Output
This is a IMPORTANT!

5.6. Admonition blocks

[NOTE]
====
This is an example of an admonition block.
Unlike an admonition paragraph, it may contain any AsciiDoc content.
The style can be any one of the admonition labels:

* NOTE
* TIP
* WARNING
* CAUTION
* IMPORTANT
====
Output

This is an example of an admonition block. Unlike an admonition paragraph, it may contain any AsciiDoc content. The style can be any one of the admonition labels:

  • NOTE

  • TIP

  • WARNING

  • CAUTION

  • IMPORTANT

6. Blocks

6.1. Listing block

-----
This is a **_listing block_**
-----
Output
This is a **_listing block_**

6.2. Example block

=====
This is a **_example block_**
=====
Output

This is a example block

6.3. Comment block

////
This is a **_comment block_**
////
Output

6.4. Literal block

....
This is a **_literal block_**
....
Output
This is a **_literal block_**

6.5. Pass block

++++
== This is raw text
++++
Output
== This is raw text

6.6. Quote/Verse block

____
This is a very very simple quote
____
Output

This is a very very simple quote

6.6.1. blockqoutes

.After landing the cloaked Klingon bird of prey in Golden Gate park:
[quote,Captain James T. Kirk,Star Trek IV: The Voyage Home]
Everybody remember where we parked.
Output
After landing the cloaked Klingon bird of prey in Golden Gate park:
Everybody remember where we parked.
— Captain James T. Kirk
Star Trek IV: The Voyage Home

6.7. Sidebar block

.Some Title
****
This is a Sidebar block -- I have no idea why it's called `sidebar`
****
Output
Some Title

This is a Sidebar block — I have no idea why it’s called sidebar

6.8. Block metadata

.Gettysburg Address
[[gettysburg]]
[quote, Abraham Lincoln, Soldiers' National Cemetery Dedication]
----
Four score and seven years ago our fathers brought forth
on this continent a new nation...
Now we are engaged in a great civil war, testing whether
that nation, or any nation so conceived and so dedicated,
can long endure. ...
----
Output
Gettysburg Address
Four score and seven years ago our fathers brought forth
on this continent a new nation...
Now we are engaged in a great civil war, testing whether
that nation, or any nation so conceived and so dedicated,
can long endure. ...

7. Customization (WIP)

8. Render (WIP)

Tags: #AsciiDoc #Documentation #Writing