1.10.2. Substitutions

Substitutions are a useful way to define a value which is needed in many places. Substitution definitions are indicated by an explicit markup start (".. ") followed by a vertical bar, the substitution text (which gets substituted), another vertical bar, whitespace, and the definition block.

A substitution definition block may contain inline-compatible directives such as Images and Figures, Downloadable Files, or other Substitution Directives:

• Replacement Text

• Unicode Character Codes

• Date

For more information, see reStructuredText Primer, section Substitutions, or refer the Substitution References. Sphinx provides additional predefined Substitutions.

.. replace::

The example

.. |RST| replace:: reStructuredText

Here, :rst:`|RST|` will be replaced by |RST|.

Which gives

Here, |RST| will be replaced by reStructuredText.

Styled Reference

You can also create a reference with styled text, nested inline markup.

the example

.. |gh| replace:: :strong:`GitHub`
.. _`gh`: https://github.com/

Here, :rst:`|gh|` will be replaced by |gh|.

You can use the hyperlink reference by appending a :rst:`"_"` at the end
of the vertical bars and :rst:`|gh|_` will be replaced by |gh|_.

which gives

Here, |gh| will be replaced by GitHub.

You can use the hyperlink reference by appending a "_" at the end of the vertical bars and |gh|_ will be replaced by GitHub.

Use Prolog and Epilog

The Sphinx configuration values rst_prolog and rst_epilog in conf.py contains a list of global substitutions that can be used from any file. The (incomplete) list for this document is given below:

"|project|"

→ leads to: “Li-Pro.Net Sphinx Primer”

"|author|"

→ leads to: “The LP/N Documentation Team”

"|publisher|"

→ leads to: “Li–Pro.Net”

"|copyright|"

→ leads to: “2020, Li–Pro.Net, The LP/N Documentation Team and individual contributors.”

"|LICENSE|"

→ leads to: “LICENSE”

"|CREDITS|"

→ leads to: “CREDITS”

Inline Image

You can add inline images in the document using substitutions. The following block of code substitutes arrow in the text with the image specified.

the example

:|lpn_16x16|: The logo as in front of this documentation.

.. |lpn_16x16| image:: /_images/lpn.*
               :alt: Li-Pro.Net.
               :height: 16px
               :width: 16px

which gives

The logo as in front of this documentation.