Structure and layout¶
These directives arrange a page rather than add a kind of content to it:
informal headings, centred lines, lists in columns, grouping blocks,
asides, a table of contents for the page, and the pages listed under it.
ubCode renders each of them in the editor preview and in its html and pdf builds,
except the list of the pages under a page, which a PDF does not draw.
The styled block quotes (epigraph, highlights and pull-quote)
are with the other quotes in Block quotes,
and section numbering (sectnum) is not supported yet
(see Numbering).
An option one of these directives does not take
makes it fall back to the generic placeholder,
which still renders its body.
Rubrics, centred lines and columns¶
A rubric is an informal heading: it is not a section,
so it opens nothing and is not listed in a table of contents.
centered prints its argument as a centred, bold line.
hlist spreads a single bullet list over :columns: columns (two unless you set it).
Rubrics, centred lines and columns
.. rubric:: An informal heading
.. centered:: A centred *line*
.. hlist::
:columns: 3
- one
- two
- three
- four
- five
An informal heading
A centred line
|
|
|
```{rubric} An informal heading
```
```{centered} A centred *line*
```
````{hlist}
:columns: 3
- one
- two
- three
- four
- five
````
The MyST form renders live in the MyST rubrics, centred lines and columns.
rubric takes :class: and :name:;
centered takes no options.
An hlist whose body is not exactly one bullet list falls back to the generic placeholder.
Grouping blocks and classes¶
A container groups its body in one block,
with the classes given as its argument, for a stylesheet to target.
A compound joins paragraphs and the blocks between them into one compound paragraph.
rst-class (also spelled cssclass), written with no body,
puts its classes on the element that follows it.
Grouping blocks and classes
.. container:: ex-structure-box
A block with the class ``ex-structure-box``.
.. compound::
Run the command
.. code-block:: shell
ubc build html docs
and open the page it writes.
.. rst-class:: ex-structure-lead
A paragraph with the class ``ex-structure-lead``.
A block with the class ex-structure-box.
Run the command
ubc build html docs
and open the page it writes.
A paragraph with the class ex-structure-lead.
```{container} ex-structure-box
A block with the class `ex-structure-box`.
```
````{compound}
Run the command
```shell
ubc build html docs
```
and open the page it writes.
````
```{rst-class} ex-structure-lead
```
A paragraph with the class `ex-structure-lead`.
The MyST form renders live in the MyST grouping blocks and classes.
container takes :name:; compound takes :class: and :name:.
Where an rst-class can and cannot put its classes is in
the CSS class differences.
Topics¶
A topic is a titled, self-contained aside, set apart from the text around it.
A topic, a sidebar and a page table of contents cannot sit inside another block —
not in a list, an admonition or a tab, and so not in a live specimen either:
a Sphinx build reports The "topic" directive may not be used within topics or body elements.
So each of these three is shown as its source, and rendered for real at the top level of this page,
straight after the tabs.
.. topic:: A topic
A self-contained aside, with a title of its own.
```{topic} A topic
A self-contained aside, with a title of its own.
```
The MyST form renders in the MyST topics.
The source renders as:
A topic takes :class: and :name:.
Where a topic sits inside another block, ubCode renders it there and reports nothing
(see the structure differences).
A table of contents for the page¶
contents lists the page’s own sections, each a link to its heading.
:depth: limits how many levels it lists,
and :local: lists only the sections inside the one it is written in.
By default each listed heading becomes a link back to its entry in the list;
:backlinks: top links it to the top of the list instead,
and none, used here, leaves the headings as they are.
:class: adds classes to the list:
the long one here is the class this site’s Sphinx theme, Furo, asks for before it shows a page table of contents.
.. contents:: On this page
:depth: 2
:backlinks: none
:class: this-will-duplicate-information-and-it-is-still-useful-here
```{contents} On this page
:depth: 2
:backlinks: none
:class: this-will-duplicate-information-and-it-is-still-useful-here
```
The MyST form renders in the MyST table of contents.
The source renders as:
What else contents honours, and where it differs from a Sphinx build, is in
the table of contents differences.
The pages under this one (toctree)¶
A toctree makes the pages it lists the children of the page it is on:
they come after it in the site’s navigation, in the previous and next links, and in the PDF,
and the list is drawn where the directive is written.
:maxdepth: limits how many levels of each page’s own headings and children the list shows,
and :hidden: keeps the pages in the navigation without drawing the list at all.
This page’s own toctree is the specimen: it lists the page’s MyST twin.
```{toctree}
:maxdepth: 1
structure_myst
```
A toctree on the MyST twin would need pages of its own to list,
so the MyST form is shown as source only.
ubc build pdf draws no list for a toctree, and nor does a Sphinx LaTeX build:
it places the listed pages after this one instead.
How a toctree entry is resolved, and what is reported, is in toctree navigation.