Inline element nesting¶

I come across this limitation very often - you can’t mix e.g. italic (called emphasis) inside bold (called strong emphasis), substitution inside italic, etc.

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

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

**A |substitution| inside bold.**

*A :subscript:`subscripts` inside italic.*

``Or, *italic* within literals.``

:ref:`link with ``literal`` inside`

The only workaround here is if you need

Emphasis inside literal

If you need italic inside literal, Sphinx offer with :samp: role that can do that. Wrap text to be emphasised into the curly braces.

Put user specific packages to :samp:`{approot}/packages/` ,
where :samp:`{approot}` is folder chosen during the installation.

The same allows also :file: role too.

Underlines and colors¶

Underline is not intentionally part of the reStructuredText. Docs, prose, and books almost never use underlines.

You can’t also intentionally “highlight” a text in certain color. Colors are representation, while reStructuredText describes text semantically (see Separation of content and representation).

Immediately succeeding inline elements¶

Inline element must be preceded and succeeded by one or more whitespace (i.e., the space character). In other words: inline elements are normally separated by the space character and thus an inline element cannot be immediately followed by an another one.

In the following incorrect example, succeeding inline elements are not separated by the whitespace and thus not recognized:

Python ``list``s use square bracket syntax.

I love *re***Structured***Text*.

Fortunately, two inline elements without no space in-between are possible with escaping mechanism using backslash character \.

Previous example fixed:

Python ``list``\s use square bracket syntax.

I love *re*\ **Structured**\ *Text*.

Spaces around the role content¶

For example, :strong:`foo `, :strong:` bar` and :strong:` foobar ` are all invalid reStructuredText, because role content (a string between two `) cannot begin or end by the whitespace.

I want to be :strong:`strong `!

I want to be :strong:` strong`!

I want to be :strong:` strong `!

Again, we can escape the whitespace with \ character.

I want to be :strong:`strong\ `!

I want to be :strong:`\ strong`!

I want to be :strong:`\ strong\ `!