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

For detailed information see the section "Literals and source code" in the AsciiDoc Syntax Quick Reference

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.

HTML code block included from an external file. The first three lines of the file are skipped.

<!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>

Listings without syntax highlighting

The [source] block used for source code listings is a special type of listing block that applies syntax highlighting. For simple text listings (e.g. console output, folder structures, etc.) you can instead use the [listing] block.

Example of a folder structure listing. It is enriched with icons for files and folders taken from the Unicode standard. You can look up the Unicode of the icons on https://emojipedia.org/ and copy them from there. ^[1]

📄 config.yml
📂 data
	📂 images
		🖼️ photo1.jpg
		🖼️ photo2.jpg
		🖼️ photo3.jpg
📂 pages
	📄 index.adoc
	📄 ranges.adoc
📂 _posts
	📄 2025-10-08-title-of-the-article.adoc

Folder structure listing from the previous example, but with a tree-like structure directly taken from the output of the tree command ^[2]. Additionally, annotations with automatic numbering are added.

📂 ./
├── 📄 config.yml (1)
├── 📂 data
│   └── 📂 images (2)
│       ├── 🖼️ photo1.jpg
│       ├── 🖼️ photo2.jpg
│       └── 🖼️ photo3.jpg
├── 📂 pages (3)
│   ├── 📄 index.adoc
│   └── 📄 ranges.adoc
└──📂 _posts (4)
    └── 📄 2025-10-08-title-of-the-article.adoc

1	config-file
2	Folder with images
3	Folder with pages
4	Folder with blog posts

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

Text replacements

Also see the section "Text replacements" in the AsciiDoc Syntax Quick Reference

-> is replaced by →
<- is replaced by ←
=> is replaced by ⇒
<= is replaced by ⇐
(C) is replaced by ©
(R) is replaced by ®
... is replaced by …
(TM) is replaced by ™
a -- b is replaced by a — b

Footnotes

Also see the section "Footnotes" in the AsciiDoc Syntax Quick Reference

A statement with a footnote. ^[3]
A statement with a footnote!^[4]
Another statement with the same footnote!^[4]

* A statement with a footnote. footnote:[Details about this statement.]
* A statement with a footnote!footnote:xyz[A named footnote with the id 'xyz'.]
* Another statement with the same footnote!footnote:xyz[]

Keyboard shortcuts, buttons and menu paths

Also see the section "Keyboard, button, and menu macros" in the AsciiDoc Syntax Quick Reference

You must add the :experimental: attribute to the document header to enable these macros.

AsciiDoc Code Result

AsciiDoc Code	Result
`kbd:[Ctrl + Alt + Del]`	`Ctrl`+`Alt`+`Del`
`menu:View[Appearance > Full Screen]`	View Appearance Full Screen
`btn:[Submit]`	Submit

kbd:[Ctrl + Alt + Del]

Ctrl+Alt+Del

menu:View[Appearance > Full Screen]

View Appearance Full Screen

btn:[Submit]

Submit

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.

Code for the inline command (here for a TIP):

TIP: Admonition: `TIP`.

Code for the block command (here for a NOTE):

[NOTE]
====
...
====

Sidebar/Aside blocks

Excursus: Sidebar block with a code example

Sidebars are used to visually separate auxiliary bits of content that supplement the main text. They typically contain more information than a simple admonition block.

They can contain any type of content.

Source code you can use to create a sidebar block. The block-delimiter is ****.

.Title of the sidebar block
****
Content of the sidebar block.
****

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
This cell spans 2 rows	Second row of the spanned cell	Another cell
Links	Supports links within the table	Example Link

Passthrough blocks

With passthrough blocks (delimited with ++++), you can embed raw HTML code directly into your AsciiDoc document. Common examples are the inclusion of an HTML form, CSS and JavaScript snippets.

Keep in mind that this only affects the HTML output. It will be visible as-is in other output formats like PDF.

To add a form to your document, you can use:

++++
<form onsubmit="alert('Thank you for subscribing!'); return false;">
  <input type="email" required placeholder="name@example.com">
  <button type="submit">Subscribe</button>
</form>
++++

The result is:

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

Numbered item 1
Numbered item 2
1. Numbered item 2.1
2. Numbered item 2.2
3. Numbered item 2.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:

AsciiMathML (AsciiMath is the default)
TeX and LaTeX

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.

The Docker image provided by jekyll-theme-endless currently ships with the software preinstalled to support the following diagram types: Ditaa, Dpic, Gnuplot, Graphviz, LilyPond, Mermaid, MscGen, Nomnoml, Pintora, PlantUML, State Machine Cat, Barcodes and QR codes, Meme, TikZ.

Ditaa

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

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.

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);

Dpic

Dpic is an implementation of the Pic-DSL (Pic Domain-Specific Language) and is especially well-suited for generating precise diagrams, graphs, and technical illustrations directly from text-based descriptions.

Figure 4. This diagram demonstrates a polar coordinate system rendered with the Pic graphics language.

Figure 5. This diagram illustrates the 'Magic Triangle of Cost, Time and Quality' created with simple pic code. Lines between the circles are colored and habe a different value for the thickness.

Gnuplot

Gnuplot is a powerful plotting utility that allows users to create a wide variety of 2D and 3D plots from data and mathematical functions. This makes it ideal for visualizing scientific data, mathematical functions, and statistical information.

Figure 6. Example of a simple parabola plotted using Gnuplot, demonstrating the function y = x² over the range from -10 to 10, with labeled axes and a title.

Graphviz

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

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

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.

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

Mermaid

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

Figure 9. Example of a Sankey diagram that shows the distribution of construction costs across different trades, as well as the material and labor costs.

Figure 10. Example of a flowchart in Mermaid, demonstrating a simple decision tree with two options.

Figure 11. 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.

MscGen

MscGen is a tool for creating message sequence charts (*MSC*s), ideal for visualizing interactions between entities (Systems, Actors, etc.) over time.

Nomnoml

Nomnoml is a simple and intuitive tool for creating UML diagrams.

Figure 12. A flowchart in Nomnoml, illustrating a decision-making process for troubleshooting a non-working lamp, including states, decisions, and actions.

Pintora

Pintora is a versatile diagramming tool that supports various types of diagrams, including activity diagrams, sequence diagrams, and class diagrams.

Figure 13. Example of a mind map created with Pintora, illustrating the categorization of UML diagrams into behavior and structural diagrams, along with specific types under each category. The diagram uses a left-to-right layout and custom colors for different levels of nodes.

Figure 14. Example of a Gantt chart created with Pintora, outlining a software project plan with various phases, tasks, and dependencies. The chart includes parameters for font color, bar gap, bar height, and grid line padding, as well as markers for the project start date and current date.

PlantUML

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

Figure 15. Example of a class diagram in PlantUML, depicting a hierarchy where DiagramBlock and BlockProcessor classes are related, with DiagramBlock having subclasses DitaaBlock and PlantUmlBlock.

Figure 16. Example of a sequence diagram in PlantUML, showing an interaction where Bob greets Alice with 'hello,' and Alice responds with 'hi.'

Figure 17. Example of a mind map illustrating concepts in the field of Artificial Intelligence (AI) and Machine Learning (ML).

State Machine Cat

State Machine Cat (smcat) is a tool for creating state machine diagrams.

Figure 18. Example ^[5] of a state machine diagram created with State Machine Cat, illustrating the behavior of a cat. The diagram demonstrates the use of colors and different line widths to enhance the visual representation of states and transitions. The diagram is laid out from left to right using the "circo" engine.

QR codes and Barcodes

For details on how to use the QR code and barcode features, see the Asciidoctor Diagram documentation on Barcodes and QR Codes.

Block version of QR Codes (PNG and SVG)

Figure 19. QR code in SVG format using a code block and a specified x-dimension (value of 7).

Figure 20. QR code in PNG format using a block macro and a specified x-dimension (value of 5).

Inline version of Barcodes and QR codes (PNG)

qrcode:
code128:
ean13:
upca:

Meme

The meme extension is based on ImageMagick and is used to create simple memes with text overlaid on images.

Example of a meme created with the Meme diagram type, featuring an image of a cat with overlaid text at the top and bottom. The text is styled with a stroke width of 2 and a white fill color to enhance visibility against the background image. During the build process the source image was available at: public/assets/images/cat.jpg.

Failed to generate image: magick failed: identify: unable to open image '/builds/jekyll-theme-endless/jekyll-theme-endless.gitlab.io/pages_examples/public/assets/images/cat.jpg': No such file or directory @ error/blob.c/OpenBlob/3596.

TikZ

TikZ is a powerful and user-friendly syntax layer built upon the PGF (Portable Graphic Format) package for creating high-quality graphics programmatically within LaTeX documents.

Figure 21. Example of a simple diagram created with TikZ, demonstrating the drawing of a grid, coordinates, and arrows between points. The diagram includes a red arrow to highlight a specific direction. The diagram is scaled by a factor of 2.3 and uses ultra thick lines for better visibility.

Figure 22. Example ^[6] of a more complex 3D diagram created with TikZ, illustrating a tetrahedron inscribed within a parallelepiped. The diagram uses perspective angles and colors to enhance the visual representation of the shapes and their vertices.

1. The icons may not be displayed correctly in all fonts and browsers. Unicode 6.0 was the first version of the Unicode Standard to support emoji.

2. The tree command is a standard Unix command used to display the directory structure of a path in a tree-like format. If not istalled, use sudo apt install tree on Debian-based systems to install it.

3. Details about this statement.

4. A named footnote with the id 'xyz'.

5. Source: Example for colors and line widths in the documentation of State Machine Cat on GitHub

6. Source: Example for a TikZ diagram taken from the AsciiDoctor-Diagram documentation

AsciiDoc showroom

Source code listings

Listings without syntax highlighting

Text formatting

Text replacements

Footnotes

Links

Keyboard shortcuts, buttons and menu paths

Admonition blocks

Sidebar/Aside blocks

Tables

Passthrough blocks

Images

Lists

Unordered

Numbered

Checklist

Quotes

Glossary

Table of contents (TOC)

Level 2 corresponds to <h3>

Level 3 corresponds to <h4>

Level 4 corresponds to <h5>

Level 5 corresponds to <h6>

Using Mathematical Formulas (STEM)

Examples using AsciiMath

Examples using LaTeX

Ascii Diagrams

Ditaa

Dpic

Gnuplot

Graphviz

Lilypond

Mermaid

MscGen

Nomnoml

Pintora

PlantUML

State Machine Cat

QR codes and Barcodes

Block version of QR Codes (PNG and SVG)

Inline version of Barcodes and QR codes (PNG)

Meme

TikZ