Skip to content

Commit

Permalink
Document indent behaviour for directives
Browse files Browse the repository at this point in the history
Mention how the indent of the contents for directives is chosen and what
the effect on directives which are sensitive to whitespace is,
e.g. code-block.
  • Loading branch information
latosha-maltba committed Sep 27, 2021
1 parent 274ee48 commit ee3f361
Showing 1 changed file with 21 additions and 1 deletion.
22 changes: 21 additions & 1 deletion doc/usage/restructuredtext/basics.rst
Original file line number Diff line number Diff line change
Expand Up @@ -410,7 +410,27 @@ following the arguments and indicated by the colons). Options must be indented
to the same level as the directive content.

The directive content follows after a blank line and is indented relative to
the directive start.
the directive start or if options are present, by the same amount as the
options.

Be careful as the indent is not a fixed number of whitespace, e.g. three, but
any number whitespace. This can be surprising when a fixed indent is used
throughout the document and can make a difference for directives which are
sensitive to whitespace. Compare::

.. code-block::
:caption: A cool example

The output of this line starts with four spaces.

.. code-block::

The output of this line has no spaces at the beginning.

In the first code block, the indent for the content was fixated by the option
line to three spaces, consequently the content starts with four spaces.
In the latter the indent was fixed by the content itself to seven spaces, thus
it does not start with a space.


Images
Expand Down

0 comments on commit ee3f361

Please sign in to comment.