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.

strong emphasis

(Also known as bold.)

Strong emphasis element is for words that have strong importance compared to surrounding text. Emphasis is typically displayed in bold font.

Strong emphasis syntax

Strong emphasis syntax is simple: wrap the text between two **.

1Put on **safety goggles** before proceeding.

Put on safety goggles before proceeding.

Alternative syntax

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

1Put on :strong:`safety goggles` before proceeding.

Put on safety goggles before proceeding.

No inline element nesting

The annoying reStructuredText limitation is you can’t nest inline element into another, e.g. strong emphasis into 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.*
3**A |substitution| inside bold.**
5*A :subscript:`subscripts` inside italic.*
7``Or, *italic* within literals.``
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 strong 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 a delimiter at the end, the beginning, and at the both. They will cause the WARNING: Inline strong start-string without end-string.

1Put on **safety goggles**before proceeding.
3Put on**safety goggles** before proceeding.
5Put on**safety goggles**before proceeding.

Fortunately, two inline elements without no whitespace/punctuation in-between are possible with escaping mechanism using backslash-escaped whitespace (backslash is \). Backslash-spaced whitespace will be removed from the output document.

Previous example fixed:

1Put on **safety goggles**\ before proceeding.
3Put on\ **safety goggles** before proceeding.
5Put on\ **safety goggles**\ before proceeding.

Put on safety gogglesbefore proceeding.

Put onsafety goggles before proceeding.

Put onsafety gogglesbefore proceeding.

Previous: sidebar | Next: subscript