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
2
3Click to the |ico1| to return home.
Click to the 
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.
2
3.. |ico2| image:: /img/small-banana.png
The inline image 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
3
4Click to the |ico3| to return home.
Click to the to return home.
Note
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.*
2
3**A |substitution| inside bold.**
4
5*A :subscript:`subscripts` inside italic.*
6
7``Or, *italic* within literals.``
8
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
3
4Click to the |ico4|\ to return home.
5
6Click to the\ |ico4| to return home.
7
8Click to the\ |ico4|\ to return home.
Click to the to return home.
Click to the to return home.
Click to theto return home.