AsciiDoc Primer

AsciiDoc is a lightweight markup language designed for writing documentation, articles, books, and more in a readable plain-text format. It is a powerful alternative to Markdown, offering enhanced formatting capabilities while remaining human-friendly.

Why Use AsciiDoc?

• Human-readable and simple: Uses a clean syntax that is easy to write and understand.
• More powerful than Markdown: Supports complex formatting, document structure, cross-references, and includes.
• Convertible: Can be transformed into HTML, PDF, EPUB, DocBook, and more.
• Ideal for technical documentation: Widely used for software documentation, particularly with Asciidoctor.

Basic Syntax

Headers

Use = signs to define section titles:

    = Document Title
    == Section 1
    === Subsection 1.1
    ==== Subsection 1.1.1
                            

Paragraphs

Plain text creates paragraphs automatically.

Bold, Italics, and Monospace

• *bold*

  → bold

• _italic_

  → italic

• `monospace`

  →

  monospace

Lists

Unordered Lists

    * Item 1
    * Item 2
    ** Sub-item 2.1
    ** Sub-item 2.2
                            

Ordered Lists

    . First item
    . Second item
    .. Sub-item 2.1
    .. Sub-item 2.2
                            

Links

    https://example.com[Example]
                            

Images

    image::example.jpg[Example Image, width=300, height=200]
                            

Code Blocks

    [source,python]
    ----
    def hello():
        print("Hello, Otto!")
    ----
                            

Tables

    [cols="3,1,2"]
    |===
    | Name | Age | Country
    | John | 30 | USA
    | Alice | 25 | UK
    |===