Block Annotations

The sphinx-immaterial theme has support for adding annotations to block level document elements. To do this, we will use the rST directive class which is re-exported by sphinx as rst-class.

Important

Please read the rST directive class documentation to better understand how Sphinx’ rst-class directive works.

See also

A special directive is needed to produce code-annotations.

Annotating paragraphs

The first block-level element that follows a rst-class directive (without directive content) is appended with the annotate class.

.. rst-class:: annotate

An annotated paragraph. (1)

An unannotated paragraph. (2)

1. I'm an annotation! I can contain ``code``, *formatted text*, images, ...
   basically anything that can be used. :si-icon:`material/emoticon-happy`
2. This won't show.

An annotated paragraph. (1)

An unannotated paragraph. (2)

  1. I’m an annotation! I can contain code, formatted text, images, … basically anything that can be used.

  2. This won’t show.

When the rst-class is given content, then all blocks within the content are appended with the annotate class.

.. rst-class:: annotate

    First paragraph (1)

    Second paragraph (2)

1. I'm an annotation!
2. I'm an annotation as well!

First paragraph (1)

Second paragraph (2)

  1. I’m an annotation!

  2. I’m an annotation as well!

Annotating lists

Lists can be annotated as well. Beware that lists are typically started and ended with a blank line. So, consecutive lists (as in the case of annotating lists) might look odd.

.. rst-class:: annotate

1. An ordered list item (1)

   1. A nested list does not need to end in a blank line.
2. A second list item (2)

1. I'm an annotation!
2. I'm an annotation as well!

  1. An ordered list item (1)

    1. A nested list does not need to end in a blank line.

  2. A second list item (2)

  1. I’m an annotation!

  2. I’m an annotation as well!

Nested annotations

Nested annotations can be done as well, although the indentation gets tricky. Beware that the paragraph within the annotated list must also be flagged with .. rst-class:: annotate, otherwise the nested annotation will just appear as a nested list.

.. rst-class:: annotate

Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.

1. .. rst-class:: annotate

   I'm an annotation! (1)

   1. I'm an annotation as well!

Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.

  1. I’m an annotation! (1)

    1. I’m an annotation as well!

Annotating admonitions

The admonition directives already contain an option to specify CSS classes. Therefor, we don’t need to use the rst-class directive for admonitions. Instead, we can just add the annotate class to the admonition’s :class: option.

.. note::
    :title: Phasellus posuere in sem ut cursus (1)
    :class: annotate

    Lorem ipsum dolor sit amet, (2) consectetur adipiscing elit. Nulla et
    euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
    purus auctor massa, nec semper lorem quam in massa.

1. I'm an annotation!
2. I'm an annotation as well!

Phasellus posuere in sem ut cursus (1)

Lorem ipsum dolor sit amet, (2) consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

  1. I’m an annotation!

  2. I’m an annotation as well!

Annotating tabbed content

Here is a simple example of annotating paragraphs within tabbed content (using Content tabs).

.. md-tab-set::

    .. md-tab-item:: Tab 1

        .. rst-class:: annotate

        Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.

        1. I'm an annotation!

    .. md-tab-item:: Tab 2

        .. rst-class:: annotate

        Phasellus posuere in sem ut cursus (1)

        1. I'm an annotation as well!

Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.

  1. I’m an annotation!

Phasellus posuere in sem ut cursus (1)

  1. I’m an annotation as well!

Annotating blockquotes

There is a noteworthy clash between the syntax for rST block-quotes versus the rST directive class. The suggested workaround is a single rST comment immediately after the rst-class invocation.

.. rst-class:: annotate
..

    A blockquote with an annotation. (1)

1. I'm an annotation!

A blockquote with an annotation. (1)

  1. I’m an annotation!

Implementation Detail

The rst-class directive is not given any content in the example above. The empty comment .. (followed by a blank line) implicitly signifies this to the rST parser.

If we instead provide a blockquote as the sole content to the rst-class directive, then indentation is normalized by the rST parser and the blockquote is interpreted as a simple paragraph.

A blockquote as sole directive content does not work
.. rst-class:: annotate

        A blockquote (normalized to a paragraph) with an annotation. (1)

1. I'm an annotation!

A blockquote (normalized to a paragraph) with an annotation. (1)

  1. I’m an annotation!

Using a blockquote as subsequent content preserves the indentation needed to satisfy the rST block-quotes specification.

A blockquote as subsequent directive content can work
.. rst-class:: annotate

    An annotated paragraph (1) which does not get annotated by the JS implementation.

        A blockquote with an annotation. (2)

1. I'm an annotation!
2. I'm an annotation as well!

An annotated paragraph (1) which does not get annotated by the JS implementation.

A blockquote with an annotation. (2)

  1. I’m an annotation!

  2. I’m an annotation as well!