. Source code
[*source]
----
This is all verbatim.
== This is not a header
[These are not attributes]
----
Source Code Blocks
The older authorities seemed rather more helpful than the newer ones, and Armitage concluded that the code of the manuscript was one of great antiquity, no doubt handed down through a long line of mystical experimenters.
For programmers, one of the most useful features of a markup language is source code blocks. Mau provides full support to source code highlighting, and allows you to highlight single lines and add callouts to the code to mark specific steps of the process or to add explanations.
Basic source blocks
Verbatim paragraphs and source code can be printed using [*source] and surrounding the code with a standard block fence
Mau source
Source code
This is all verbatim.
== This is not a header
[These are not attributes]
You can specify the language of the source code immediately after *source
Mau source
[*source,python]
----
def header_anchor(text, level):
"""
A simple Python function
"""
return "h{}-{}-{}".format(
level, quote(text.lower())[:20], str(id(text))[:8]
) # pragma: no cover
----
def header_anchor(text, level):
"""
A simple Python function
"""
return "h{}-{}-{}".format(
level, quote(text.lower())[:20], str(id(text))[:8]
) # pragma: no cover
Highlighting for the HTML output format is provided by Pygments. On the official website you can find the list of supported languages. If you want to use third-party tools like JavaScript libraries you can set highlighter=none for a specific block or set mau.visitor.highlighter to "none" in the global configuration.
Mau source
[*source,python]
----
# This code is not highlighted
def add(a, b):
return a + b
----
# This code is not highlighted
def add(a, b):
return a + b
Callouts
Source blocks support callouts, that allow you to add notes to specific lines of code. Callouts are added at the end of the line between colons (e.g. :1:) the relative text is added to the secondary content of the block
Mau source
[*source,python]
----
def header_anchor(text, level)::1:
return "h{}-{}-{}".format(
level, quote(text.lower())[:20], str(id(text))[:8]:2:
) # pragma: no cover
----
1: The name of the function
2: Some memory-related wizardry
def header_anchor(text, level): 1
return "h{}-{}-{}".format(
level, quote(text.lower())[:20], str(id(text))[:8] 2
) # pragma: no cover
| 1 | The name of the function |
| 2 | Some memory-related wizardry |
The default delimiter for callouts is a colon :, but if that clashes with the syntax of your language you can pick a different one with the attribute callouts
Mau source
[*source, python, callouts="|"]
----
def header_anchor(text, level):|1|
return "h{}-{}-{}".format(
level, quote(text.lower())[:20], str(id(text))[:8]|2|
) # pragma: no cover
----
1: The name of the function
2: Some memory-related wizardry
def header_anchor(text, level): 1
return "h{}-{}-{}".format(
level, quote(text.lower())[:20], str(id(text))[:8] 2
) # pragma: no cover
| 1 | The name of the function |
| 2 | Some memory-related wizardry |
Callouts names are just strings, not manipulated by Mau, so you can use them out of order
Mau source
[*source,python]
----
def header_anchor(text, level)::1:
return "h{}-{}-{}".format(:3:
level, quote(text.lower())[:20], str(id(text))[:8]:2:
) # pragma: no cover
----
1: The name of the function
2: Some memory-related wizardry
3: This is the return value
def header_anchor(text, level): 1
return "h{}-{}-{}".format( 3
level, quote(text.lower())[:20], str(id(text))[:8] 2
) # pragma: no cover
| 1 | The name of the function |
| 2 | Some memory-related wizardry |
| 3 | This is the return value |
Callouts are not limited to digits, you can use non-numeric labels
Mau source
[*source,python]
----
def header_anchor(text, level)::step1:
return "h{}-{}-{}".format(:step3:
level, quote(text.lower())[:20], str(id(text))[:8]:step2:
) # pragma: no cover
----
step1: The name of the function
step2: Some memory-related wizardry
step3: This is the return value
def header_anchor(text, level): step1
return "h{}-{}-{}".format( step3
level, quote(text.lower())[:20], str(id(text))[:8] step2
) # pragma: no cover
| step1 | The name of the function |
| step2 | Some memory-related wizardry |
| step3 | This is the return value |
Callouts do not need to have a definition
Mau source
[*source,python]
----
def header_anchor(text, level)::1:
return "h{}-{}-{}".format(
level, quote(text.lower())[:20], str(id(text))[:8]:2:
) # pragma: no cover
----
def header_anchor(text, level): 1
return "h{}-{}-{}".format(
level, quote(text.lower())[:20], str(id(text))[:8] 2
) # pragma: no cover
And you can reference them in the text using [class](1, "callout"), and rendering it accordingly.
Highlight lines
You can highlight lines using a callout with the special name @
Mau source
[*source,python]
----
def header_anchor(text, level)::@:
return "h{}-{}-{}".format(
level, quote(text.lower())[:20], str(id(text))[:8]:@:
) # pragma: no cover
----
def header_anchor(text, level):
return "h{}-{}-{}".format(
level, quote(text.lower())[:20], str(id(text))[:8]
) # pragma: no cover
Should you prefer to list the lines you want to highlight you can use Pygments directly, passing the configuration value hl_lines under the namespace pygments
Mau source
[*source,python,pygments.hl_lines="1,3"]
----
def header_anchor(text, level):
return "h{}-{}-{}".format(
level, quote(text.lower())[:20], str(id(text))[:8]
) # pragma: no cover
----
def header_anchor(text, level):
return "h{}-{}-{}".format(
level, quote(text.lower())[:20], str(id(text))[:8]
) # pragma: no cover
Titles
Code blocks support titles
Mau source
. Header anchor function
[*source]
----
def header_anchor(text, level):
"""
A simple Python function
"""
return "h{}-{}-{}".format(
level, quote(text.lower())[:20], str(id(text))[:8]
) # pragma: no cover
----
Header anchor function
def header_anchor(text, level):
"""
A simple Python function
"""
return "h{}-{}-{}".format(
level, quote(text.lower())[:20], str(id(text))[:8]
) # pragma: no cover