Code blocks

See how code blocks look like in your Sphinx project with the Awesome Theme and learn about the supported options.

To check the styles for inline markup looks like, see Inline code.

Sphinx code-block directive

To document code blocks with syntax highlighting, use Sphinx’s code-block directive.

You can provide the language used for syntax highlighting as an argument to the code-block directive:

.. code-block:: python

   print("Hello World")

This renders as:

print("Hello World")

If you don’t provide a language to the directive, Sphinx uses a fallback:

  1. If you used the highlight directive to set a default language for the current document, any code block after this directive is highlighted with the language you specified.

  2. If you set the global fallback language for highlighting in the Sphinx configuration file with the highlight_language option, this language is used as default.

See also

Showing code examples highlight directive highlight_language

Tip

It’s usually better to be explicit. It makes your documentation more portable if you want to copy or re-use your documentation files elsewhere. It’s also easier to follow for contributors who may not be as familiar with Sphinx and restructuredtext.

Feature: The Awesome Theme adds a Copy button to every code block, so that your users can easily copy your code.

Add captions to code blocks

Add captions to code blocks with the :caption: CAPTION_TEXT option:

Example code
console.log("Hello World")

Adding a caption also adds a link target to the code block. Hover over a caption to see the headerlink icon.

Show line numbers in code blocks

Show line numbers in code blocks with the :linenos: option:

1for i in range(3):
2   print(f"{i} line of code")

Highlight lines in code blocks

To highlight specific lines in code blocks, use the :emphasize-lines: LINE_NUMBERS option:

echo "Don't emphasize this"
echo "Emphasize this"
echo "Don't emphasize this either"

Highlight changes in code blocks

Feature: The Awesome Theme adds two new options to the code-block directive for highlighting added or removed lines of code:

:emphasize-added:

Highlight added lines with :emphasize-added: LINE_NUMBERS.

:emphasize-removed:

Highlight removed lines with :emphasize-added: LINE_NUMBERS.

.. code-block:: python
   :emphasize-removed: 1
   :emphasize-added: 2

   print("red")
   print("green")
   print("regular highlighting is applied")

This example highlights the first line in red, and the second line in green:

print("red")
print("green")
print("regular highlighting is applied")

The :emphasize-added: and :emphasize-removed: options preserve the syntax highlighting. If you copy the code, the + and - characters aren’t copied.

If you don’t want to use these options, you can use Pygments’ built-in diff language:

+ print("red")
- print("green")
  print("no highlighting is applied here")

Here, the syntax isn’t highlighted. If you copy the code to the clipboard, the + and - characters are copied as well.

The following example is for testing the previous options with line numbers:

1print("One line of code")
2print("Removed line of code")
3print("Added line of code")
4print("Emphasized line of code")
5print("Normal line of code")

Highlighting short lines doesn’t work well if you also have long, overflowing lines:

A really long line
print("A shorter line of code.")
print("And a really long line of code that should overflow the container on most screen sizes which illustrates the issue.")

You can’t include markup in code blocks, such as bold text or hyperlinks.

Highlight placeholders in code blocks

Feature: The Awesome Theme adds an :emphasize-text: option to the code-block directive for highlighting placeholder text in code blocks:

.. code-block:: python
   :emphasize-text: WORLD

   print("Hello WORLD")

This renders as:

print("Hello WORLD")

Naturally, this should also work in combination with captions:

Caption text
print("Hello WORLD")
print("Added line")
print("Removed line")

Note

Separate multiple placeholders by space, not by comma. For example, :emphasize-text: WORD1 WORD2 highlights both WORD1 and WORD2.

Docutils code directive

The code-block directive only works with Sphinx. If you want to re-use your reStructuredText documentation outside Sphinx, you can also use the code directive:

.. code:: bash

   echo "This is rendered with the docutils' code directive"

This renders:

echo "This is rendered with the docutils' code directive"

You can’t use captions, highlighted lines, or any of the other options for Sphinx code blocks.

See also

Code directive (docutils)

Parsed literal blocks

Parsed literal blocks can contain either markup or syntax. If you add markup, such as bold text or hyperlinks, syntax highlighting is turned off.

For example:

.. parsed-literal::

   This *can* contain markup, but **not** syntax highlighting.
   How about a `link <https://example.org>`_?

This renders as:

This can contain markup, but not syntax highlighting.
How about a link?

If you don’t include any markup, the content is rendered with syntax highlighting.

print("Hello world")

See also

Parsed-literal directive (docutils)

Prompt characters

Prompt characters shouldn’t be selected when copying code.

For example, if you copy the code from the following console code block, the $ character should not be copied:

$ echo "Prompt characters not selected"

The same is true for Python interactive sessions:

>>> print("Prompt characters not selected.")

Output should also not be selected when copying:

>>> api.execute(circuit=c)
[1168]