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.

emphasis

(Also known as italic or cursive.)

Emphasis element is for words that have a stressed emphasis compared to surrounding text. Emphasis is typically displayed in italic.

Emphasis syntax

Emphasis syntax is simple: wrap the text between two *.

1Get out of bed *now*, John!

Get out of bed now, John!

Alternative syntax

Alternative to enclosing into * is to use a full role syntax: :emphasis:`text to emphasis`.

1Get out of bed :emphasis:`now`, John!

Get out of bed now, John!

No inline element nesting

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

1Don't get out of bed *before*six.
2
3Don't get out of bed*before* six.
4
5Don't get out of bed*before*six.

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:

1Don't get out of bed *before*\ six.
2
3Don't get out of bed\ *before* six.
4
5Don't get out of bed\ *before*\ six.

Don’t get out of bed beforesix.

Don’t get out of bedbefore six.

Don’t get out of bedbeforesix.

Previous: danger | Next: error