Code Blocks

Displaying Code in Documents

In technical documentation, code examples are essential. AsciiDoc offers flexible ways to display code both inline within text and in separate blocks.

For inline code within running text, use backticks:

The command `git status` shows the current status.

Result: The command git status shows the current status.

Code Blocks with Syntax Highlighting

For multi-line code examples, use a source block:

[source,python]
----
def greet(name):
    return f"Hello, {name}!"

print(greet("World"))
----

The result with syntax highlighting:

def greet(name):
    return f"Hello, {name}!"

print(greet("World"))

The key elements:

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

  • ---- encloses the code block (four dashes).

adoc Studio supports highlighting for many languages: Python, JavaScript, Java, Swift, Ruby, SQL, HTML, CSS, Bash, and many more.

Callouts for Explanations

With callouts, you can explain individual code lines directly:

[source,python]
----
def calculate(x, y):    1
    result = x + y      2
    return result       3
----
<1> Function definition with two parameters
<2> Calculation of the result
<3> Return of the value

The result:

def calculate(x, y):    1
    result = x + y      2
    return result       3
1 Function definition with two parameters
2 Calculation of the result
3 Return of the value

The callout markers <1>, <2>, <3> in the code refer to the explanations below. With :icons: font in the document header, the numbers are displayed as small circles.

For code blocks without syntax highlighting, use a simple listing block – just ---- without [source,language].