Documenting Software in AsciiDoc

In technical documentation, code examples are essential. AsciiDoc offers a simple and flexible way to display code both inline within a sentence and in multi-line code blocks.

How to Insert Code Blocks

[source,python]
----
def hello():
    print("Hallo, AsciiDoc!")

hello()
----

  • [source,python] defines the language for syntax highlighting.

  • ---- encloses the code block.

Callouts for Explanations

AsciiDoc allows adding callouts to code lines to explain individual parts:

[source,python]
----
def hello(): // <1>
    print("Hello, AsciiDoc!") // <2>

hello() // <3>
----
<1> Defines the function `hello`
<2> Prints a greeting
<3> Calls the function

  • The callouts <1>, <2>, <3> refer to explanations below the code block.

  • They enable a direct link between the code and its explanation.

Customizing Callout Icons

The appearance of callout numbers can be adjusted using the :icons: attribute:

:icons: font

  • font uses standard font characters for callouts.

  • image replaces them with small graphics if the corresponding images are available.

As mentioned in the video, the images for :icons: image must be placed in the media directory in a separate subfolder called callouts. Name each image according to the respective callout number and set :iconsdir: in the document header.

Back
Next