Code

Inline code is marked up using backticks as follow: `code`, which produces code.

To specify the language for syntax highlighting, add {l=language} after the closing `. For example `return x % 2`{l=py} produces return x % 2.

For blocks of code there are three methods for marking up code. All of them apply syntax syntax highlighting, i.e. use different colours for different parts of the code, according to the syntax of the programming language.

When moving the mouse over a code block, a copy button appears. Clicking on it copies the code to the clipboard.

Code blocks

To display a basic block of syntax-highlighted code, write:

```language
lines of code
```

Note that this uses three backticks to mark the block, not three colons. It will not work with three colons.

The language can be md (Markdown), py (Python), java, bash, etc. If the language is text, the content is displayed in black as-is, preserving line breaks and indentations. Here are a few examples for common languages.

Language py:

def f(x: int) -> bool:
    """Check a mysterious property.""""
    return x % 2 == 0

Language text:

1. *text* and `text`
   - [a link](#code-blocks)

Language md:

1. *text* and `text`
   - [a link](#code-blocks)

If you need to discuss particular lines of code in the text, you can number and highlight by adding the lineno-start and emphasize-lines attributres using the following syntax:

{lineno-start=1 emphasize-lines="1,3"}
```py
def f(x: int) -> bool:
    """Check a mysterious property.""""
    return x % 2 == 0
```

The example above produces

def f(x: int) -> bool:
    """Check a mysterious property.""""
    return x % 2 == 0

Code blocks should be used for short examples that aren’t referenced elsewhere, or where a reference like ‘the code example in section Code blocks’ is unambiguous.

Code listings

To number and refer to code listings, use the code-block block. For example

:::{code-block} py
:linenos:
:emphasize-lines: 1, 2
:name: poor-doc
:caption: A poorly named and documented function.

def f(x: int) -> bool:
    """Check a mysterious property.""""
    return x % 2 == 0
:::

produces

Listing 1 A poorly named and documented function.

def f(x: int) -> bool:
    """Check a mysterious property.""""
    return x % 2 == 0

The linenos option takes no values; it simply turns on line numbering.

Every option (linenos, emphasize-lines, etc.) can be omitted.

If no options are given, then

:::{code-block} language
:::

produces the same output as

```language
```

Code listings can be referred to using the standard referencing syntax.

Code files

If the code example is part of a file given to students, you can copy the relevant part into the Markdown file, but that may create extra work to keep the listing in sync with the file. Alternatively you can use hte literalinclude block. For example

:::{literalinclude} ../../conf.py
:start-at: html
:end-before: latex
:lineno-match:
:caption: The HTML configuration in {file}`../conf.py`.
:::

will extract and number lines from the file given as the block title, from the first line (inclusive) that has the text ‘html’ to the first line (exclusive) that has the text ‘latex’. The code file path is relative to the MyST file that lists the code. The code file’s extension determines the programming language used for syntax highlighting. Here’s the result:

Listing 2 The HTML configuration in ../conf.py.

html_title = "OU Book Theme"
html_theme = "ou_book_theme"

myst_enable_extensions = [
    "amsmath",
    "attrs_inline",
    "attrs_block",
    "colon_fence",
    "deflist",
    "dollarmath",
    "fieldlist",
    "html_admonition",
    "html_image",
    "replacements",
    "smartquotes",
    "strikethrough",
    "substitution",
    "tasklist",
]

Other options you can use with this directive:

• name, linenosand emphasize-lines as for {code-block}

• start-after and end-at, to set the start line (exclusive) and end line (inclusive)

• lines to list the exact lines to include, e.g. :lines: 1, 5-9, 30-

• language to set a language different from the extension

• pyobject to include only a certain Python class, method or function, e.g. :pyobject: Stack.pop

The lineno-match option can only be used when selecting one group of consecutive lines.