Code blocks

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

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:

rst
.. code-block:: python

   print("Hello World")

This renders as:

python
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

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:

javascriptExample 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 or hide the highlighting language

feature The Awesome Theme shows the language used for syntax highlighting in a code block header. If you want to turn this off, set the option html_awesome_code_headers to False.

Show line numbers in code blocks

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

python
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:

bash
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, that lets you highlight added or removed lines.

:emphasize-added:

Highlight added lines with :emphasize-added: LINE_NUMBERS.

:emphasize-removed:

Highlight removed lines with :emphasize-added: LINE_NUMBERS.

rst
.. 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:

python
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:

diff
+ 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:

python
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:

pythonA 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, that lets you highlight placeholders in code blocks:

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

   print("Hello WORLD")

This renders as:

python
print("Hello WORLD")

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:

rst
.. code:: shell

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

This renders:

shell
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.

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:

rst
.. 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.

python
print("Hello world")