inline literal#

Inline literal element is typically used for short code examples displayed in monospace font.

Inline literal syntax#

Inline literal syntax is simple: wrap the text between two ``.

1To search on your disk, use ``find`` command.

To search on your disk, use find command.

Tricky examples#

Writing inline literals containing ` seems complicated, but it is not if you realize everything starting `` and ending `` is rendered as-is - no need to doubling ``, no backslash-escaping \`, etc.

1Single backtick: `````
2
3Double backtick: ``````

Single backtick: `

Double backtick: ``

Alternative syntax#

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

1To search on your disk, use :literal:`find` command.

To search on your disk, use find command.

Backslashes in alternative syntax#

``Basic`` and alternative :literal:`syntax` are treat backslashes (\) differently.

For strings not contaings backslashes, they are equivalent:

``text``
:literal:`text`

In the basic syntax, backslashes are preserved. In alternative syntax backslash is the escaping character. Backslash alone escape immediatelly following character, e.g. the space. To use backslash, you must escaped it too, which results in doubled backslash.

 1Not escaped backslashes:
 2:literal:`C:\Users\matt\AppData`
 3
 4Properly escaped:
 5:literal:`C:\\Users\\matt\\AppData`
 6
 7Or, easiest use classic syntax:
 8``C:\Users\matt\AppData``
 9
10That preserves backslashes as-is
11``text \ and \ backslashes``
12
13While in :literal:, even spaces must be escaped:
14:literal:`text \ and \ backslashes`

Not escaped backslashes: C:UsersmattAppData

Properly escaped: C:\Users\matt\AppData

Or, easiest use classic syntax: C:\Users\matt\AppData

That preserves backslashes as-is text \ and \ backslashes

While in :literal:, even spaces must be escaped: text and backslashes

No inline element nesting#

The annoying reStructuredText limitation is you can’t nest inline element into another, e.g. inline literal 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 inline literal 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 literal start-string without end-string.

1Any ``array``s will suffice.
2
3Any``array`` will suffice.
4
5Any``array``s will suffice.

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:

1Any ``array``\ s will suffice.
2
3Any\ ``array`` will suffice.
4
5Any\ ``array``\ s will suffice.

Any arrays will suffice.

Anyarray will suffice.

Anyarrays will suffice.

Common issues#

Don’t interchange ` and ``#

There is a big difference between `code example` and ``code example``! Only the latter with double `` is inline code example! Text wrapped in single ` is so-called default role interpreted text.

This is tricky part of reStructuredText because in Markdown, code examples are in wrapped in single backtick.

I am `not a code example` anyway.

Fixed:

I am ``a code example`` anyway.