Code blocks

code-block directive

The code-block directive is defined by Sphinx, the syntax looks like:

.. code-block:: language
   :linenos:
   :caption: text for caption
   :emphasize-lines: 2,10-15

   code content here, please keep a blank line above

code-block directive accepts several options:

• caption: to display a caption of the code block

• linenos: to show line numbers of the code block

• lineno-start: to set the first line number of the code block

• emphasize-lines: to emphasize particular lines of the code block

• name: to define a reference target

• class: to add extra class names for the code block

• dedent: to strip indentation for the code block

Here shows some of the use cases for code-block directive.

Highlight

The code-block directive accepts a program language after its directive name:

Highlight with a language

.. code-block:: python

   import mistune

   def render_markdown(text: str) -> str:
       """A simple function to render text in markdown format."""
       return mistune.html(text)

   render_markdown("Hello **Shibuya**.")

import mistune

def render_markdown(text: str) -> str:
    """A simple function to render text in markdown format."""
    return mistune.html(text)

render_markdown("Hello **Shibuya**.")

Captions

It is also possible to add a caption option in code-block. For example, here displays the code of markdown.py:

.. code-block:: python
    :caption: markdown.py

And the final result on Shibuya theme:

markdown.py

import mistune

def render_markdown(text: str) -> str:
    """A simple function to render text in markdown format."""
    return mistune.html(text)

render_markdown("Hello **Shibuya**.")

Line numbers

Adding a linenos option to show the code block’s line numbers:

.. code-block:: python
    :linenos:

This is how it looks with Shibuya theme:

import mistune

class Shibuya:
    def render_markdown(self, text: str) -> str:
        """A simple function to render text in markdown format."""
        return mistune.html(text)

If both caption and linenos options are added:

markdown.py

import mistune

class Shibuya:
    def render_markdown(self, text: str) -> str:
        """A simple function to render text in markdown format."""
        return mistune.html(text)

Emphasize lines

The code-block directive offers an emphasize-lines option to highlight the chosen lines:

.. code-block:: python
    :emphasize-lines: 1,5-6,24-29

markdown.py

import mistune

def render_markdown(text: str) -> str:
    """A simple function to render text in markdown format."""
    return mistune.html(text)

render_markdown("Hello **Shibuya**.")

code directive

The code is a built-in directive in reStructuredText. When using rst as the markup format in Sphinx, code directive can also be used.

.. code:: python

   import mistune

   mistune.html("Hello **Shibuya**")

import mistune

mistune.html("Hello **Shibuya**")

parsed-literal directive

The parsed-literal is a built-in directive in reStructuredText. It constructs a literal block where the text is parsed for inline markup.

For example:

.. parsed-literal::

   $ pip install shibuya==\ |version|

Above markup will turn into:

$ pip install shibuya==2024.10.15

Dark code

Dark code block can be defined with a class dark-code:

.. code-block:: python
   :class: dark-code

   html_theme_options = {
       "dark_code": True
   }

html_theme_options = {
    "dark_code": True
}

It is also possible to enable dark code mode for the whole page. You can even enable dark code mode for the whole site.

Important

This :class: option does not work well together with caption.