Vertical Space in reStructuredText

In reStructuredText (reST), there is no specific directive exclusively for adding vertical space. However, you can achieve vertical spacing using a combination of techniques, such as blank lines, comments, or substitution definitions. Below are the common methods to add vertical space in reST.

1. Using Blank Lines

The simplest way to add vertical space is by inserting blank lines between paragraphs or sections. Each blank line creates a small vertical gap in the rendered output.

Example:

This is the first paragraph.

This is the second paragraph, separated by a blank line.

2. Using Comments

You can use comments (..) to create larger vertical gaps. Since comments are ignored by the parser, multiple comment lines can act as vertical spacing.

Example:

This is the first paragraph.

..
   This is a comment used to create vertical space.
..
   Adding multiple comment lines increases the gap.

This is the second paragraph, with extra vertical space above it.

3. Using Substitution Definitions

You can define a substitution for vertical space using raw HTML (if your output format supports it, such as HTML or PDF). This method is more advanced and requires enabling raw HTML in your reST configuration.

Example:

.. |vspace| raw:: html

   <div style="margin-bottom: 2em;"></div>

This is the first paragraph.

|vspace|

This is the second paragraph, with custom vertical space.

4. Using Raw LaTeX (for PDF Output)

If you are generating PDF output (e.g., with Sphinx and LaTeX), you can use raw LaTeX to add vertical space.

Example:

.. raw:: latex

   \vspace{2cm}

This is the first paragraph.

.. raw:: latex

   \vspace{1cm}

This is the second paragraph, with custom vertical space.

5. Using CSS (for HTML Output)

If your output format is HTML, you can use raw HTML with inline CSS to add vertical space.

Example:

.. raw:: html

   <div style="margin-bottom: 50px;"></div>

This is the first paragraph.

.. raw:: html

   <div style="margin-bottom: 30px;"></div>

This is the second paragraph, with custom vertical space.

6. Using Admonitions (Indirect Spacing)

Admonitions (e.g., .. note::, .. warning::) inherently add vertical space around them. You can use an empty admonition to create spacing.

Example:

This is the first paragraph.

.. note::
   This note adds vertical space around it.

This is the second paragraph, with vertical space added by the note.

Summary of Methods

Method	Use Case	Example
Blank Lines	Simple spacing between paragraphs	Add one or more blank lines between paragraphs.
Comments	Larger gaps	Use multiple `..` comment lines to create vertical space.
Substitution + HTML	Custom spacing in HTML output	Define a substitution with raw HTML for precise control.
Raw LaTeX	Custom spacing in PDF output	Use `\vspace{}` in raw LaTeX blocks.
Raw HTML + CSS	Custom spacing in HTML output	Use raw HTML with inline CSS for precise control.
Admonitions	Indirect spacing	Use an admonition (e.g., `.. note::`) to add space around content.

Recommendation

For simple spacing, use blank lines or comments.
For precise control in HTML output, use raw HTML with CSS.
For PDF output, use raw LaTeX.
Avoid overusing vertical space, as it can make the document harder to read. Use it sparingly and only when necessary.