reStructuredText and Sphinx Reference

Example based gentle reference of the reStructuredText and Sphinx syntax, directives, roles and common issues. It demonstrates almost all the markup making it also good for testing Sphinx themes. Free and open-source.


Subscript role displays its text as subscript (with a lowered baseline using smaller text). Subscript is used in e.g., chemical formulas.

Subscript syntax

Subscript syntax itself is simple: :sub:`text as subscript`.

1In vino veritas, in H\ :sub:`2`\ O sanitas.

In vino veritas, in H2O sanitas.


See bellow the meaning of awkward \<space>.

No inline element nesting

The annoying reStructuredText limitation is you can’t nest inline element into another, e.g. subscript into strong emphasis, etc. Unfortunately, there is no workaround.

Some examples of inline markup nesting that don’t work:

1*You can't have **bold** inside italic.*
3**A |substitution| inside bold.**
5*A :subscript:`subscripts` inside italic.*
7``Or, *italic* within literals.``
9:ref:`link with ``literal`` inside`

You can’t have **bold* inside italic.*

A |substitution| inside bold.

A :subscript:`subscripts` inside italic.

Or, *italic* within literals.

link with ``literal` inside`

Requires whitespace or punctuation around

The subscript requires whitespace or punctuation around (as all inline-level elements). Without the delimiter, reStructuredText will not recognize markup properly from a surrounding text.

The following examples miss a delimiter both at the and beginning and end. It will cause the WARNING: Inline interpreted text or phrase reference start-string without end-string..

1In vino veritas, in H:sub:`2`O sanitas.

Fortunately, two inline elements without no whitespace/punctuation in-between are possible with escaping mechanism using backslash-escaped whitespace (backslash is \). Backslash-escaped whitespace will be removed from the output document.

Previous example fixed:

1In vino veritas, in H\ :sub:`2`\ O sanitas.

In vino veritas, in H2O sanitas.

Previous: strong emphasis | Next: substitution