Code Formatting for the ReadTheDocs System

You need to define the "language" of the code block in your source document. Both Sphinx and MkDocs will attempt to guess the language, which often is good enough. However, on occasion, it will guess incorrectly and result in weird highlighting. To avoid that, both implementations provide a mechanism to manually define the language of each code block.

Sphinx

For Sphinx, you can use the code-block directive and include the "language" of the block:

.. code-block:: console

    You shell commands go here

In the above example, I used console for the a shell session. The alias shell-session would work as well. Note that the alternative lexer bash (and its aliases: sh, ksh, zsh, and shell) woudl not strictly be appropriate as they are for a shell script, whereas you are displaying both the command and theoutput in a shell session.

A complete list of supported language codes can be found in the Pygments documentation.

MkDocs

MkDocs makes use of the Fenced Code Block Markdown extension to define the "language" of a code block:

``` shell
Your shell commands go here
```

As MkDocs uses highlight.js rather than Pygments, the list of supported languages is different. Therefore, I used shell (for a shell-session) in the above example.