QuickStart-Blog
Start blogging with Jekyll & AsciiDoc

AsciiDoc showroom

Here are a few examples to demonstrate what AsciiDoc, as a markup language, has to offer. Its capabilities far exceed those of Markdown. Thus, this page will only cover a small portion to give you a sense of what’s possible.

Checking out the source code of this page can also help you get started with AsciiDoc. For more information, you can refer to the official AsciiDoc and Asciidoctor documentation.

Source code listings

Python source code (language is shown in the upper right corner):
# Python code
def greet(name):
    print(f"Hello, {name}!")

greet('World')
Code block with an unknown language (language info ist not shown):
Start
Set counter to 0
While counter < 5 do
    Print "This is loop iteration", counter
    Increment counter by 1
End
Python code block with annotations.
def square(number):(1)
    return number ** 2

result = square(4)(2)
print(result)(3)
1 The function square calculates the square of a given number.
2 The function is called with the number 4, and the result is stored in result.
3 The result is printed to the console.

You can also directly insert source code from a file into your AsciiDoc document. This way, you can display the same code in multiple places but only need to update it in one location. You can even embed production code directly.

Source code of the AsciiDoc Showroom:
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Document</title>
</head>
<body>
    HTML boilerplate code.
</body>
</html>

Text formatting

  • Text with strong significance to me

  • Emphasized text

  • Combination of both

  • You can also format parts of a word:

    • Create, Read, Update, and Delete (CRUD)

    • Counterclockwise

    • strings

  • superscript

  • subscript

  • This is strikethrough text

  • This is underlined text

  • monospace text

Keyboard shortcuts and menu paths

Ctrl+Alt+Del

View  Appearance  Full Screen

Admonition blocks

Admonition: TIP.
Admonition: IMPORTANT.

Admonition blocks (here shown for the admonition: NOTE) can contain several lines and complex content like:

A list with several items.

  • one

  • two

  • three

And even blocks with source code.
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}
Admonition: CAUTION.
Admonition: WARNING.

Tables

Table 1. A simple table
Name Age City

Max Mustermann

30

Berlin

John Doe

45

New York

Maria Musterfrau

28

München
Table 2. Table showcasing AsciiDoc table capabilities
Feature Description Example

Bold and Italics

Supports italic and bold text formatting

Italic and bold formatting

This cell spans 3 columns

This cell spans 2 rows

First row of the spanned cell

Another cell

Second row of the spanned cell

Another cell

Links

Supports links within the table

Example Link

Images

The sun setting next to the trunk of an old tree.
Figure 1. Image by jplenio published on Pixabay.

Lists

Unordered

  • Item 1

  • Item 2

    • Item 2.1

    • Item 2.2

    • Item 2.3

  • Item 3

Numbered

  1. Numbered item 1

  2. Numbered item 2

    1. Numbered item 2.1

    2. Numbered item 2.2

    3. Numbered item 2.3

  3. Numbered item 3

Checklist

  • checked: * [*]

  • checked: * [x] (lower case x!)

    • checked: - [*]

    • checked: - [x]

    • unchecked: - [ ]

  • unchecked: * [ ]

    • item without checkbox

    • unchecked item on level 2: ** [ ]

      • checked item on level 3: * [x]

Quotes

Fully annotated quote:

After being searched for Lorem ipsum:

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

— Wikipedia
published on https://en.wikipedia.org/wiki/Lorem_ipsum

Quotation lacking attribution and further information:

Veni, vidi, vici.

Glossary

Glossary entries can also contain lists, quotations, code-blocks, …​

Lorem ipsum

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Lorem ipsum (with code block)

A common form of Lorem ipsum in a code block.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Lorem ipsum (with list)

  • Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

  • Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

  • Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.

  • Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Table of contents (TOC)

As you can see at the top of this page, AsciiDoc can also generate a table of contents for you.

You can enable this directly in the AsciiDoc page attributes. For this page I used:

:toc: preamble
:toclevels: 5

Level 2 corresponds to <h3>

Level 3 corresponds to <h4>

Level 4 corresponds to <h5>
Level 5 corresponds to <h6>

Using Mathematical Formulas (STEM)

In this blog, you can easily use STEM (Science, Technology, Engineering and Math) expressions in your pages and posts. To do this, simply add the :stem: attribute to the document header of your page or post (You can also enable it for all posts in your _config.yml):

= Page Title
:stem:

Two syntaxes for the formulas are are available:

Examples using AsciiMath

Inline Command: (here \$[[a,b],[c,d]]((n),(k))\$.)

\$[[a,b],[c,d]]((n),(k))\$.

Block command:

The formula for the sum of cubes.
\$sum_(i=1)^n i^3=((n(n+1))/2)^2\$
The AsciiDoc code using AsciiMath that was used to create the above formula for the sum of cubes.
[asciimath]
++++
sum_(i=1)^n i^3=((n(n+1))/2)^2
++++

Examples using LaTeX

Inline command (here: \(C = \alpha + \beta Y^{\gamma} + \epsilon\)):

\(C = \alpha + \beta Y^{\gamma} + \epsilon\)

Block command:

Exponential Decay: The limit of the exponential function \(exp(-x)\) as \(x\) approaches infinity is zero.
\[\lim\limits_{x \to \infty} \exp(-x) = 0\]
The AsciiDoc code for the exponential decay equation shown above, written in LaTeX syntax.
[latexmath]
++++
\lim\limits_{x \to \infty} \exp(-x) = 0
++++

Ascii Diagrams

Text-based diagrams enable easy integration with version control systems, as they are saved in plain text. This format avoids binary files, making changes visible in diffs, so you can track updates precisely over time. Additionally, because they are text, different themes and styles can be applied without needing to redesign the diagram. Another benefit is that these diagrams can be generated automatically during the build process, eliminating the need for graphics editors or manual exports to specific formats. This makes them ideal for automated workflows and consistent documentation across projects.

Asciidoctor Diagram supports a wide range of text-based diagram types making it a versatile choice for creating diagrams directly within documentation.

Ditaa

Ideal for converting ASCII art into diagrams, especially useful for quick sketches and block diagrams.

Diagram
Figure 2. Example of a Ditaa diagram illustrating the flow of processing in Asciidoctor Diagram, where a text document is converted through Asciidoctor with Ditaa to produce a PNG output, showcasing the transformation from plain text to visually structured output.

Check the AsciiDoc source of this page to see that the diagram is clearly recognizable even in the text. This is a unique feature of Ditaa.

Diagram
Figure 3. Example of a table-style diagram in Ditaa, illustrating a 2x2 matrix layout with labeled cells and placeholder mathematical expressions, showcasing how different background colors can be applied to each cell.(Parameter: a=4, b=6);

PlantUML

Great for creating UML diagrams like class diagrams, sequence diagrams, and activity diagrams.

Diagram
Figure 4. Example of a class diagram in PlantUML, depicting a hierarchy where DiagramBlock and BlockProcessor classes are related, with DiagramBlock having subclasses DitaaBlock and PlantUmlBlock.
Diagram
Figure 5. Example of a sequence diagram in PlantUML, showing an interaction where Bob greets Alice with 'hello,' and Alice responds with 'hi.'

Graphviz

Useful for directed and undirected graphs, including flowcharts, state diagrams, and dependency graphs.

Diagram
Figure 6. Example of a directed graph in Graphviz, illustrating nodes with connections, including a self-loop on node b and cyclical paths between nodes.

Mermaid

mermaid.js is ideal for creating flowcharts, sequence diagrams, Gantt charts, and more.

Diagram
Figure 7. Example of a Sankey diagram that shows the distribution of construction costs across different trades, as well as the material and labor costs.
Diagram
Figure 8. Example of a flowchart in Mermaid, demonstrating a simple decision tree with two options.
Diagram
Figure 9. Example of a pie chart in Mermaid, showing the popularity of different types of cuisine worldwide. Additionally, the use of the background attribute in Mermaid is demonstrated, with the color set to FFEEDD.

Lilypond

LilyPond is a music engraving program that enables users to create beautifully typeset sheet music through a text-based input system, focusing on producing high-quality, professional-looking scores suitable for publication.

Diagram
Figure 10. Example of a melody in LilyPond notation, demonstrating a simple sequence of notes with pitches relative to the starting note c'.