Quick Reference: Writing RST#

RST is very powerful and flexible. Below we provide a quick guide for how you can use it to write Open edX documentation.

For more details check out the RST Primer


Heading 1

There should be only 1 Heading 1 per topic, as the topic title.

Heading 2

Heading 2s denote the main sections of a topic.

Heading 3

Heading 3s denote subsections under Heading 2s

Heading 4

Heading 4s denote subsections under Heading 3s

Inline Markup#

RST supports bold, italic, and mono-spaced characters. You can also make GUI elements appear as GUI elements.

Use double asterisks for **bold** text.

Use single asterisks for *italic* text.

Use double backticks for ``mono-spaced`` text.

Use the guilabel role for :guilabel:`GUI elements`


You can make numbered, and bulleted lists that can nest arbitrarily, using the # symbol for ordered lists and * for unordered lists.

#. Item 1
                        # Need this blank line between items and sub-items
   * Sub-item 1         # Sub-items also need to be indented by 3 or more spaces
   * Sub-item 2

#. Item 2

This codeblock is used for the following published list:

  1. Item 1

    • Sub-item 1

    • Sub-item 2

  2. Item 2



RST can do a lot of things via directives. Here are some common ones:

.. warning::  This is a warning.

   It will be styled to stand-out in the documentation.

.. note:: This is a note.

   It will stand-out but not as much as a warning.

.. image:: path/to/image.png
   :alt: Alternative text for accessibility.

.. code-block::python

   Some python code.

.. seealso::

   `Link to a thing <https://example.com>`_
      A brief description of the thing

   `Link to another thing <https://example.com/other>`_
      A brief description of another thing.

Learn More#

See also

RST Primer

The primer has a lot more detail about the concepts behind the markup.

RST Docs

If you want even more details, check out full RST Docs.