Restructured Text (Sphinx) Image in Heading?

Question

Is it possible to place an image inside of a heading using Restructured Text?

Something like:

Introduction .. image:: path/to/img.png
---------------------------------------

This renders as text, i.e. the image syntax is not parsed. I have not seen any examples of this leading me to believe it might not be possible, but perhaps someone has a work-around.

I intend to output to HTML (so a modification to the derived CSS is possible, though I would prefer to alter the RST source. This is because I also intend to output to pdf (latex).

Answer 1

This can be achieved by using a substitution in the header:

Header Text |foo|
=================

.. |foo| image:: path/to/img.png

Here foo is just an example substitution text. It can be anything, but should not start or end with a whitespace.

The abstract substitution syntax is as follows:

+-------+-----------------------------------------------------+
| ".. " | "|" substitution text "| " directive type "::" data |
+-------+ directive block                                     |
        |                                                     |
        +-----------------------------------------------------+

As we would like to insert an inline image, we should choose the image as the directive type.