reStructuredText basics¶
The constructs of plain reStructuredText that need no directive:
inline markup, sections, lists, literal and line blocks, block quotes, transitions, and comments.
ubCode parses all of them, in the editor preview and in its html and pdf builds,
the way docutils does.
Each specimen shows its MyST spelling too, where MyST has one.
Inline markup¶
Asterisks mark emphasis and strong emphasis, double backquotes a literal, and a backslash makes the next character plain text. A backslash before a space removes the space, so markup can start inside a word.
Inline markup
Text can be *emphasised*, **strong**, or ``literal``.
A backslash keeps \*these asterisks\* as text,
and joins markup to a word: un\ *believ*\ able.
Text can be emphasised, strong, or literal.
A backslash keeps *these asterisks* as text,
and joins markup to a word: unbelievable.
Text can be *emphasised*, **strong**, or `literal`.
A backslash keeps \*these asterisks\* as text,
and joins markup to a word: un*believ*able.
The MyST form renders live in
the MyST inline markup.
MyST needs no backslash-space: emphasis with * can start and end inside a word.
reStructuredText markup does not nest. A literal inside strong text is not a literal, and neither Sphinx nor ubCode reports it:
**Run ``ubc build`` first**
renders the whole line strong, with the backquotes printed as text. Split the spans instead:
**Run** ``ubc build`` **first**
Sections¶
A section title is a line of text underlined — or over- and underlined — with a line of one punctuation character at least as long as the title. Which character means which level is not fixed: the first style a document uses is level 1, the next new one level 2, and so on, so a document must use its styles consistently.
Page title
==========
A section
---------
A subsection
~~~~~~~~~~~~
Every heading on this page is one: the page title is underlined with =,
and each section, like this one, with -.
A title cannot be shown inside a live specimen,
because a section may not start inside a directive’s body:
there Sphinx reports Unexpected section title.
and ubCode reports block.title_disallowed.
In MyST a section title is a line starting with # (one per level),
and its level is the number of #;
a title underlined with === or --- is also a level 1 or level 2 title.
Bullet and enumerated lists¶
A bullet list item starts with -, * or +;
an enumerated item with a number, a letter or a Roman numeral and a . or ),
or with #. to number it automatically.
A nested list is indented to the item’s text, with a blank line around it.
Bullet and enumerated lists
- A bullet item.
- Another, with a nested list:
#. numbered automatically,
#. and so on.
3. An enumerated list can start at any number.
4. The next item follows on.
A bullet item.
Another, with a nested list:
numbered automatically,
and so on.
An enumerated list can start at any number.
The next item follows on.
- A bullet item.
- Another, with a nested list:
1. numbered automatically,
1. and so on.
3. An enumerated list can start at any number.
4. The next item follows on.
The MyST form renders live in the MyST lists. In MyST every item’s own number is ignored but the first.
Definition lists¶
A definition list pairs a term, on a line of its own, with its definition, indented on the lines below.
A definition list
Term
Its definition.
Another term
Its definition,
over two lines.
- Term
Its definition.
- Another term
Its definition, over two lines.
MyST writes a definition list only with its deflist extension,
which this site does not enable, so there is no MyST specimen.
Field lists¶
A field list is a list of names between colons, each with a body.
At the very top of a document, a field list is the page’s metadata (:orphan:, for instance)
rather than visible content.
A field list
:Owner: The platform team
:Status: Reviewed,
over two lines.
- Owner:
The platform team
- Status:
Reviewed, over two lines.
MyST writes a field list only with its fieldlist extension,
which this site does not enable, so there is no MyST specimen.
Option lists¶
An option list documents command-line options: each option, with its argument, then at least two spaces, then its description.
An option list
--output=FILE Write the output to FILE.
-q, --quiet Print nothing.
--version Print the version and exit.
- --output=FILE
Write the output to FILE.
- -q, --quiet
Print nothing.
- --version
Print the version and exit.
MyST has no option list.
Literal blocks¶
A paragraph ending in :: introduces a literal block:
the indented lines after it are shown exactly as written.
:: at the end of a sentence prints as one colon;
on a line of its own it prints as nothing.
A literal block
The configuration reads::
[parse]
extensions = ["sphinx.ext.todo"]
The configuration reads:
[parse]
extensions = ["sphinx.ext.todo"]
The configuration reads:
```
[parse]
extensions = ["sphinx.ext.todo"]
```
The MyST form renders live in the MyST literal block.
A literal block is highlighted in the language of the last .. highlight:: above it,
or the project’s highlight_language
(a Sphinx build with neither highlights it as Python;
see the code-block differences);
to name its language, write a code block instead.
Line blocks¶
A line block keeps its line breaks, for an address or a verse:
each line starts with | and a space,
and a line indented further is nested.
The line-block directive writes the same thing without the bars.
Line blocks
| The first line,
| the second line,
| and an indented third.
.. line-block::
The ``line-block`` directive
keeps these *two* lines apart.
line-block directive```{line-block}
The `line-block` directive
keeps these *two* lines apart.
```
The MyST form renders live in
the MyST line block.
MyST has no | spelling.
ubCode renders a nested line flat, where a Sphinx build indents it (see the structure differences).
Doctest blocks¶
A paragraph that starts with >>> is a doctest block:
an interactive Python session, shown as written
(highlighted as one in a Sphinx build and in ubc build pdf, plain in ubc build html;
see the code-block differences).
A doctest block
>>> 1 + 1
2
>>> 1 + 1
2
MyST has no doctest block; write a pycon code fence.
Block quotes¶
The epigraph, pull-quote and highlights directives each set their body apart as a quote,
styled by the directive’s name:
an epigraph opens a section, a pull quote repeats a line of the text, and highlights sum it up.
Block quotes
.. epigraph::
A quote that opens a section.
.. pull-quote::
Every specimen on this page is rendered from the source above it.
.. highlights::
Use a directive for a quote, never bare indentation.
A quote that opens a section.
Every specimen on this page is rendered from the source above it.
Use a directive for a quote, never bare indentation.
```{epigraph}
A quote that opens a section.
```
```{pull-quote}
Every specimen on this page is rendered from the source above it.
```
```{highlights}
Use a directive for a quote, never bare indentation.
```
> A Markdown block quote is a line starting with `>`.
The MyST form renders live in the MyST block quotes.
reStructuredText also makes a block quote of any paragraph indented more than the one before it:
A paragraph.
An indented paragraph is a bare block quote.
Because a stray indent produces the same thing, ubCode reports it as (wrapped here):
block.bare_blockquote: Bare blockquotes can lead to unexpected parsing and may be a result
of mis-indentation, instead use the pull-quote or epigraph directives.
so write one of the three directives instead.
A trailing -- Author line in a quote is an attribution in a Sphinx build
and a plain paragraph in ubCode (see the structure differences).
Transitions¶
A transition is a line of four or more repeated punctuation characters, with a blank line on each side, between two paragraphs; it renders as a horizontal rule.
The end of one topic.
----
The start of the next.
Like a section title, it cannot be shown inside a live specimen
(Sphinx reports Unexpected section title or transition., ubCode block.title_disallowed).
A section or document may not begin with one, nor the document end with one:
a Sphinx build warns about both, and ubCode does not report them
(see the structure differences).
In MyST a transition is a line of three or more -, * or _.
Comments¶
A line starting with
..that is not a directive, target, footnote, citation or substitution definition is a comment, and everything indented under it belongs to the comment. A comment renders nothing.A comment
Only this paragraph is rendered.
The MyST form renders live in the MyST comment.