reStructured Text Special directives

https://cheat.readthedocs.io/en/latest/rst.html

Fig. 138 map to buried treasure

Note

Begin Grid table:

Header 1	Header 2	Header 3
body row 1	column 2	column 3
body row 2	Cells may span columns.
body row 3	Cells may span rows.	Cells contain blocks.
body row 4

Note

Begin Simple table:

Inputs		Output
A	B	A or B
False	False	False
True	False	True
False	True	True
True	True	True

Error

Beware killer rabbits!

Important

important here

Note

note here

Tip

tip here

Warning

warning here

admonition here

you can make your own admonition here

So what I feel is very important

Is this key point right here, you know?

Special directives

colored boxes: note, seealso, todo and warnings

There are simple directives like seealso that creates nice colored boxes:

See also

This is a simple seealso note.

created using:

.. seealso:: This is a simple **seealso** note. Other inline directive may be included (e.g., math :math:`\alpha`) but not al of them.

You have also the note and warning directives:

Note

This is a note box.

Warning

note the space between the directive and the text

A transition marker is a horizontal line of 4 or more repeated punctuation characters.

---

A transition should not begin or end a section or document, nor should two transitions be immediately adjacent.

This is the caption of the figure (a simple paragraph).

The legend consists of all elements after the caption. In this case, the legend consists of this paragraph and the following table:

Note

Begin Table 1

Symbol	Meaning
cat1	Campground
cat2	Lake
cat3	Mountain

End Table 1

Note

Begin Table 2

Header 1	Header 2	Header 3
body row 1	column 2	column 3

End Table 2

Note

Begin Table 3Revised

Symbol	Meaning
example1	Campground
example2	Lake
example3	Mountain

End Table 3Revised

This format is the most natural and obvious. It was independently invented (no great feat of creation!), and later found to be the format supported by the Emacs table mode:

Note

Begin Table 4

Header 1	Header 2	Header 3	Header 4
Column 1	Column 2	Column 3 & 4 span (Row 1)
Column 1 & 2 span		Column 3	Column 4 Row 2 & 3 span
1	2	3

End Table 4

Tables are described with a visual outline made up of the characters ‘-‘, ‘=’, ‘|’, and ‘+’:

The hyphen (‘-‘) is used for horizontal lines (row separators). The equals sign (‘=’) is optionally used as a header separator (as of version 1.5.24, this is not supported by the Emacs table mode). The vertical bar (‘|’) is used for for vertical lines (column separators). The plus sign (‘+’) is used for intersections of horizontal and vertical lines. Row and column spans are possible simply by omitting the column or row separators, respectively. The header row separator must be complete; in other words, a header cell may not span into the table body. Each cell contains body elements, and may have multiple paragraphs, lists, etc. Initial spaces for a left margin are allowed; the first line of text in a cell determines its left margin.

Below is a simpler table structure. It may be better suited to manual input than alternative #1, but there is no Emacs editing mode available. One disadvantage is that it resembles section titles; a one-column table would look exactly like section & subsection titles.

The table begins with a top border of equals signs with a space at each column boundary (regardless of spans). Each row is underlined. Internal row separators are underlines of ‘-‘, with spaces at column boundaries. The last of the optional head rows is underlined with ‘=’, again with spaces at column boundaries. Column spans have no spaces in their underline. Row spans simply lack an underline at the row boundary. The bottom boundary of the table consists of ‘=’ underlines. A blank line is required following a table.

There are three forms of hyperlink currently in StructuredText:

(Absolute & relative URIs.) Text enclosed by double quotes followed by a colon, a URI, and concluded by punctuation plus white space, or just white space, is treated as a hyperlink:

“Python”:http://www.python.org/ (Absolute URIs only.) Text enclosed by double quotes followed by a comma, one or more spaces, an absolute URI and concluded by punctuation plus white space, or just white space, is treated as a hyperlink:

“mail me”, mailto:me@mail.com (Endnotes.) Text enclosed by brackets link to an endnote at the end of the document: at the beginning of the line, two dots, a space, and the same text in brackets, followed by the end note itself:

Please refer to the fine manual [GVR2001].

The problem with forms 1 and 2 is that they are neither intuitive nor unobtrusive (they break design goals 5 & 2). They overload double-quotes, which are too often used in ordinary text (potentially breaking design goal 4). The brackets in form 3 are also too common in ordinary text (such as [nested] asides and Python lists like [12]).

Last change: Tue, 03 Aug 2021 10:25 PM UTC