Make your documentation awesome

Make the most out of your Sphinx documentation by using the features of the awesome theme.

Highlight placeholder text in code blocks

To highlight text in code blocks, that users should replace with their own instances, you can add the emphasize-text: PLACEHOLDER option to the code-block directive.

For example:

rst
.. code-block::
   :emphasize-text: PLACEHOLDER

   echo "Replace PLACEHOLDER text"

renders as:

shell
echo "Replace PLACEHOLDER"

Highlight code changes

Sometimes, you want to highlight changes in code. The awesome theme adds two options to the code-block directive.

To highlight removed lines in a code snippet, use the emphasize-removed option. To highlight added lines, use the emphasize-added option.

For example:

rst
.. code-block:: shell
   :emphasize-removed: 1
   :emphasize-added: 2

   echo "Hello World"
   echo "Hello You"

renders as:

shell
echo "Hello World"
echo "Hello You"

Note

You can also use the built-in diff language to get a similar effect:

rst
.. code-block:: diff

   + echo "Hello You"
   - echo "Hello World"

renders as:

diff
+ echo "Hello You"
- echo "Hello World"

Using this approach, you only highlight the changes. The rest of the lines render as plain text without syntax highlighting. If you copy the code, the + and - characters are copied as well.