| Author: | Nathaniel Beaver |
|---|---|
| Date: | 2014-08-01 (Friday, 1 August 2014) |
| Copyright: | This document has been placed in the public domain. |
If you are reading an output format like HTML, the source file is ../readme.rst. If you are reading on Github, the source file is ./readme.rst. (Note that Github does not support all reStructuredText directives; notably the math directive is not supported at all as of June 2019.)
This is meant to be read from the source file. It is more of a template than a tutorial, and reading the output is not as helpful.
See also the official reStructuredText demo:
http://docutils.sourceforge.net/docs/user/rst/demo.txt
http://docutils.sourceforge.net/docs/user/rst/demo.html
Unofficial guides:
http://www.trueelena.org/computers/articles/restructuredtext_for_fiction.html
Run the Makefile to generate HTML by default,
or make all to generate all possible formats.
Contents
Plain URLs will usually create a standalone hyperlink:
https://en.wikipedia.org/wiki/ReStructuredText
If there are underscores or asterisks in the URL, the bare URL may not work, in which case escape each with a backslash or use the explicit hyperlink syntax:
https://en.wikipedia.org/wiki/Cluster_(spacecraft)#Launch_failure>
https://en.wikipedia.org/wiki/Cluster_(spacecraft)#Launch_failure
<http://web.archive.org/web/*/http://ntrs.nasa.gov/*
http://web.archive.org/web/*/http://ntrs.nasa.gov/*
Unlike Markdown, parentheses in URLs do not need to be escaped.
Named hyperlink targets make the markup easier to read, e.g.:
The reStructuredText specification is on Sourceforge, as is the docutils Quick Reference.
The Wikipedia page on reST is also helpful, as is the Sphinx documentation generator page.
Inline hyperlinks are also possible, although I find them harder to read in the source markup.
Anonymous hyperlinks are also possible if you don't want to name your hyperlinks, or if you want two hyperlinks with the same text (e.g. Georgia or Georgia, can or can).
They are assigned by the order of the links in the document, unlike named hyperlink targets where order is irrelevant.
Some characters must be escaped in links,
including some characters in URLs.
Backslashes (\) must be escaped in both the link text and the target,
a leading underscore (_) must be escaped in the target,
and colons (:) must be escaped anywhere in the target.
For example, to link to the title "LaTeX: a document preparation system", the colon does not need to be escaped in the link text, but it does in the target.
To link to _why, the leading underscore does not need to be escaped in the link text, but it does in the target.
To link to C:\Program Files\, the backslash must be escaped in both the link text and the target.
The backtick (`) must be escaped in the link text, but does not need to be escaped in the target.
Relative and absolute links both work.
For example, we can make a relative link to the source file in the parent directory, or link to the same file inline.
Absolute links are done similarly.
Path to image on Github page:
Path to image on local version
(HTML file is in out/, so image is in parent directory):
In HTML output, this generates an img tag.
A limited subset of image attributes are supported,
including alt, height, width, scale, align, target.
Tags can be wrapped by aligning with the indentation:
The height and width attributes can be expressed in units of length
like pixels, or as a percentage of the page.
More documentation here:
http://docutils.sourceforge.net/docs/ref/rst/directives.html#image
Linking to the section on how to do math.
Inline link to the title.
Linking to the section on unordered/bulleted lists.
Linking to an arbitrary cross-reference target.
blah blah blah blah
blah blah blah blah
From the documentation:
- Underline is different than underline and overline.
- Do not indent the title for underline-only section titles.
- Valid section adornment characters:
! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~ - Reccomended section adornment characters:
= - ` : . ' " ~ ^ _ * + #
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections
Example of turning an rst markup document into HTML:
rst2html reStructuredText.rst reStructuredText.html
The quadratic equation, a x^2 + b x + c = 0, has two solutions, x = \frac{-b \pm \sqrt{b^2 - 4 a c} }{2 a}.
The Einstein field equations.
G_{\mu\nu} \equiv R_{\mu\nu} - \frac{1}{2} R g_{\mu\nu} = \frac{8 \pi G}{c^4} T_{\mu\nu}
You can also use MathJax by defining a raw-latex directive.
Inline math is done like this: \( \vec{F} = e \vec{v} \times \vec{B} \)
Displayed math is done like this:
\[ e \vec{v} \times \vec{B} = m \frac{d \vec{v}}{dt} \]References:
- http://docutils.sourceforge.net/docs/ref/rst/roles.html#math
- http://docutils.sourceforge.net/docs/ref/rst/directives.html#math
Subscripts and superscripts can be done like so: this text is superscript this text is subscript.
If you want the superscript right after some text without additional space, use a backslash preceding the space. For example: the density of lead at standard temperature and pressure is 11.34 g/cm3.
This is sufficient for exponents and simple chemical reactions, such as lithium uptake reaction for the cathode material in a lithium iron phosphate battery:
FePO4 + Li+ + e- → LiFePO4
or the thermite reaction:
2 Al + Fe2O3 → 2 Fe + Al2O3
However, it is not sufficient for more complex formatting such as isotopes. However, this can be done reasonably well in math mode. Here is a fusion reaction between deuterium and tritium:
^{2}_{1}\mathrm{D} + ^{3}_{1}\mathrm{T} \to
^{4}_{2}\mathrm{He} \mathrm{(3.5 MeV)} +
n^{0} \mathrm{(14.1 MeV)}
Writing out chemical formulas repeatedly with :sup: and :sub:
can get tiresome.
To make this easier, we can use the replace:: directive like so:
Now we can use them like this:
2 H2 + O2 → 2 H2O
References:
- http://docutils.sourceforge.net/docs/ref/rst/roles.html#subscript
- https://docutils.sourceforge.io/docs/ref/rst/directives.html#replacement-text
Cheese is delicious. [1]
Labeled footnotes? Why bother? [2]
(Don't forget that space between the body text and the [#]_;
you won't get an error, but the footnote won't show up.)
Symbolic footnotes: there are ten symbols to run through before it starts doubling them up. [*] [†] [‡] [§] [¶] [#] [♠] [♥] [♦] [♣] [**]
Citations with the label instead of a number are easy. [jdoe2014]
Note that the location of a footnote's target does affect the placement of the footnotes in the document. So if you want the footnotes to actually be at the bottom of the document, you have to put the target down there, too.
| [1] | Here's an example of a multi-line footnote: cheese varieties include brie, cheddar, edom, emmentaler, jarlsberg, fontina, gouda, limburger, mascarpone, parmesan, provolone, and more! |
| [2] | You can always add a label later. |
| [*] | Asterisk *. |
| [†] | Dagger †. |
| [‡] | Double dagger ‡. |
| [§] | Section sign §. |
| [¶] | Pilcrow/paragraph sign ¶. |
| [#] | Number sign #. |
| [♠] | Black spade suit ♠. |
| [♥] | Black heart suit ♥. |
| [♦] | Black diamond suit ♠. |
| [♣] | Black club suit ♣. |
| [**] | Double asterisk **. |
| [jdoe2014] | Doe, John. Bulletin of Stuff. 2104. |
A multiplication table.
| 1 | 2 | 3 | 4 | |
| 1 | 1 | 2 | 3 | 4 |
| 2 | 2 | 4 | 6 | 8 |
| 3 | 3 | 6 | 9 | 12 |
| 4 | 4 | 8 | 12 | 16 |
A less laborious multiplication table; the first cell cannot be empty or have multiple lines.
| x | 1 | 2 | 3 | 4 |
| 1 | 1 | 2 | 3 | 4 |
| 2 | 2 | 4 | 3 | 8 |
| 3 | 3 | 6 | 9 | 12 |
| 4 | 4 | 8 | 12 | 16 |
Tables with a header row.
| X | Y |
|---|---|
| 1 | 1 |
| 2 | 4 |
| 3 | 9 |
| 4 | 16 |
| X | Y |
|---|---|
| 1 | 1 |
| 2 | 4 |
| 3 | 9 |
| 4 | 16 |
Lists in tables.
|
|
- One example
- using hyphens.
- Another using
- asterisks.
- Another using
- plus signs.
- Nesting levels: 1st.
- 2nd level.
- 2nd level again.
- 3rd level.
- 3rd level again.
- 4th level.
- 4th level again.
- 5th level.
Any language benefits from the ability to comment things out.
If we use rst2html, we get this output:
<!-- This won't appear, since we used two dots. -->
If we use rst2latex, we get this output:
% This won't appear, % since we used two dots.
This is a block quote. It is indented, and does not preserve line-breaks.
If you want to start a new paragraph, you must leave a blank line.
This is an indented line block.It preserves line-breaks, and is useful for poems and other verse.
This is a literal block. It is indented, uses monspace font, and preserves line-breaks. Don't forget to leave a blank space before the leading ::.