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.

inline image

Inline images are used for showing small images as part of the line of a text - for example, an icons. They are similar to normal block-level image.

Inline image syntax

Inline image is actually the substitution, i.e. it has two parts – the definition and usage:

1.. |ico1| image:: /img/small-banana.png
3Click to the |ico1| to return home.

Click to the ico1 to return home.

Image definition and usage

The inline image usage may even come before the image definition.

1The inline image |ico2| usage may even come before the image definition.
3.. |ico2| image:: /img/small-banana.png

The inline image ico2 usage may even come before the image definition.

Setting image options

Inline image accepts all options as their block image counterpart.

For example, to limit icon height to fit text line height, use ex unit:

1.. |ico3| image:: /img/small-banana.png
2   :height: 2ex
4Click to the |ico3| to return home.

Click to the ico3 to return home.


Resized images are by default links to original image files. This is usually undesired for inline images like icons. To prevent it for a particular icon, add :class: no-scaled-link option to the image:: directive.

.. |ico3| image:: /img/small-banana.png
   :height: 2ex
   :class: no-scaled-link

Click to the |ico3| to return home.

See more at Resized image without a link to the original file.

No inline element nesting

The annoying reStructuredText limitation is you can’t nest inline element into another, e.g. inline image 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 inline image 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 at the end, the beginning, and at the both. They will cause the WARNING: Inline substitution_reference start-string without end-string..

Click to the |ico|to return home.

Click to the|ico| to return home.

Click to the|ico|to return home.

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:

1.. |ico4| image:: /img/small-banana.png
2   :height: 1em
4Click to the |ico4|\ to return home.
6Click to the\ |ico4| to return home.
8Click to the\ |ico4|\ to return home.

Click to the ico4to return home.

Click to theico4 to return home.

Click to theico4to return home.

Previous: important | Next: inline literal