Source blocks

How to highlight source code

The engine source is used to create blocks that highlight source code. The whole content of the block is read verbatim, but the block adds styles and other support structures like line numbers and markers.

A source block can be created with engine=source. The programming language syntax used to highlight the code can be specified with the argument language.

[engine=source, language=python]
----
def sum(a, b):
    return a + b
----

def sum(a, b):
    return a + b

Syntactic sugar

Since source code is one of the most common components of technical blogs and books, Mau provides a shortcut to engine=source through the alias @source. Also, the argument language can be the first unnamed argument.

All the following examples are equivalent and produce the same output.

[engine=source, language=python]
----
def sum(a, b):
    return a + b
----

[@source, language=python]
----
def sum(a, b):
    return a + b
----

[@source, python]
----
def sum(a, b):
    return a + b
----

def sum(a, b):
    return a + b

def sum(a, b):
    return a + b

def sum(a, b):
    return a + b

Markers

The engine source supports markers, that is labels attached to a specific line of code.

Such labels can be rendered as an actual label at the end of the line to provide a visual anchor when explaining code. The standard syntax is :LABEL: put directly at the end of the line. Here, :1: attaches the label 1 to the line.

[@source, python]
----
def sum(a, b):
    return a + b:1:
----

def sum(a, b):
    return a + b 1

Markers text

Markers can contain any string that will be used verbatim.

[@source, python]
----
def sum(a, b):
    return a + b:clever:
----

def sum(a, b):
    return a + b clever

Markers delimiter

If the syntax :LABEL: clashes with the programming language you are highlighting, you can use the argument marker_delimiter to use a different character than :.

[@source, python, marker_delimiter="|"]
----
def sum(a, b):
    return a + b|1|
----

def sum(a, b):
    return a + b 1

Highlight lines

Source blocks can also highlight lines of code. In terms of the Mau parser, highlighting means simply to attach a label to a special slot of every line, but when it comes to rendering, such slot is made available to the visitor and can be interpreted in many ways by the template.

A source line can be highlighted using a marker that starts with @.

[@source, python]
----
def sum(a, b):
    # This line will be highlighted with the style `border`
    # which in this manual corresponds to a thin border
    # around the line.
    return a + b:@border:
----

def sum(a, b):
    # This line will be highlighted with the style `border`
    # which in this manual corresponds to a thin border
    # around the line.
    return a + b

Highlight aliases

Mau defines 5 aliases for highlight styles that might come handy when showing source code. See the chapter about the configuration file to learn how to define custom aliases.

• @ becomes @default
• @+ becomes @add
• @- becomes @remove
• @! becomes @important
• @x becomes @error

[@source, python]
----
# The output you see here is ruled by the custom
# templates and the CSS styles used by this site.

# A demo of the highlight styles (full names)
full_demo = [
    "default",:@default:
    "add",:@add:
    "remove",:@remove:
    "important",:@important:
    "error",:@error:
]

# A demo of the highlight styles (short names)
short_demo = [
    "default",:@:
    "add",:@+:
    "remove",:@-:
    "important",:@!:
    "error",:@x:
]
----

# The output you see here is ruled by the custom
# templates and the CSS styles used by this site.

# A demo of the highlight styles (full names)
full_demo = [
    "default",
    "add",
    "remove",
    "important",
    "error",
]

# A demo of the highlight styles (short names)
short_demo = [
    "default",
    "add",
    "remove",
    "important",
    "error",
]

<pre class="p-3">
  ...

  <span class="c1"># A demo of the highlight styles (short names)</span>
  <span class="n">short_demo</span> <span class="o">=</span> <span class="p">[</span>

  <span class="hll-default">
    <span class="s2">"default"</span><span class="p">,</span>
  </span>

  <span class="hll-add">
    <span class="s2">"add"</span><span class="p">,</span>
  </span>

  <span class="hll-remove">
    <span class="s2">"remove"</span><span class="p">,</span>
  </span>

  <span class="hll-important">
    <span class="s2">"important"</span><span class="p">,</span>
  </span>

  <span class="hll-error">
    <span class="s2">"error"</span><span class="p">,</span>
  </span>

  ...

</pre>

Customise the highlight syntax

Injecting special formatting commands in source code is never a simple business. Should you have trouble with the highlight marker @ you can change it passing a different character to the block option highlight_marker.

The default style used to highlight code lines is simply called default, but you can change it passing the new name to the block option highlight_default_style.

[@source, python, highlight_marker="#", highlight_default_style="error"]
----
# A demo of the highlight styles (short names)
short_demo = [
    "default",:#:
    "add",:#+:
    "remove",:#-:
    "important",:#!:
    "error",:#x:
]
----

# A demo of the highlight styles (short names)
short_demo = [
    "default",
    "add",
    "remove",
    "important",
    "error",
]