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")
Copy code

This renders as:

print("Hello World")
Copy code

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")
Copy code

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:

for i in range(3):
   print(f"{i} line of code")
Copy 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"
Copy code

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")
Copy code

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

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

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")
Copy code

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:

print("One line of code")
print("Removed line of code")
print("Added line of code")
print("Emphasized line of code")
print("Normal line of code")
Copy 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.")
Copy code

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")
Copy code

This renders as:

print("Hello WORLD")
Copy code

Naturally, this should also work in combination with captions:

Caption text

print("Hello WORLD")
print("Added line")
print("Removed line")
Copy code

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"
Copy code

This renders:

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

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>`_?
Copy code

This renders as:

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

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

print("Hello world")
Copy code

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"
Copy code

The same is true for Python interactive sessions:

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

Output should also not be selected when copying:

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