Page state¶

These directives print little or nothing where you write them. They change something about the page instead: how the text after them is read, what the page’s <head> carries, or what a writer other than HTML does with it. Those that change how later text is read do so from where you write them to the end of the page, so each such specimen here ends by changing it back, or comes last on the page. In the editor preview, default-role, default-domain, highlight and role each show as a small marker chip, so you can see where the page changes. The role directive, which defines a custom role from that point of the page on, is with the other roles in The default role and custom roles.

The default role¶

Text in bare single backticks, with no role named, takes the default role: :title-reference:, unless the default_role key of the parsing configuration sets another for every page. default-role names the role from that point of the page on, and with no argument it returns to :title-reference:.

reStructuredText

The default role

.. default-role:: emphasis

From here, `bare text` is emphasis.

.. default-role::

From here, `bare text` is a title reference again.

From here, bare text is emphasis.

From here, bare text is a title reference again.

MyST

MyST has no default role: text in single backticks is inline code there, so the directive has no MyST form.

The default domain¶

default-domain names the domain in which a directive or role written without a domain prefix is looked up first, from that point of the page on. The default is the py domain, which is where this specimen returns.

reStructuredText

The default domain

.. default-domain:: std

From here, a name without a domain is looked up in ``std`` first.

.. default-domain:: py

From here, a name without a domain is looked up in std first.

MyST

```{default-domain} std
```

From here, a name without a domain is looked up in `std` first.

```{default-domain} py
```

The MyST form renders live in the MyST default domain.

ubCode records the domain but looks nothing up through it yet: the directives and roles it knows without a prefix are the standard ones and those of Sphinx-Needs, whatever the default domain says.

Page metadata¶

meta writes <meta> tags into the <head> of the built page, one for each field of its body, and prints nothing into the page itself. This specimen gives this page a keywords tag.

reStructuredText

Page metadata

.. meta::
   :keywords: ubCode, page state

The ``meta`` directive above prints nothing here.

The meta directive above prints nothing here.

MyST

---
html_meta:
  keywords: ubCode, page state
---

In MyST the tags are written as html_meta front matter at the top of the file, which belongs to a whole page, so this form is not shown live.

What is written, in which order, and how a malformed field is reported, are in Page <head> meta tags.

The browser title¶

title sets what the browser tab and the search results call the page, without renaming its heading anywhere else. It changes the title of the page it is on, wherever on the page it is written, so it is shown here as source only.

reStructuredText

.. title:: Page state, for the browser tab

MyST

```{title} Page state, for the browser tab
```

What it does and does not change is in A page can override its browser title.

LaTeX column specs¶

tabularcolumns gives the column specification a LaTeX build uses for the next table. Neither an html build nor ubc build pdf uses it, so it prints nothing, and the table after it renders as usual.

reStructuredText

LaTeX column specs

.. tabularcolumns:: |l|L|

.. list-table::
   :header-rows: 1

   * - Name
     - Meaning
   * - ``stage``
     - How far the document has come.

Name	Meaning
`stage`	How far the document has come.

MyST

```{tabularcolumns} |l|L|
```

| Name    | Meaning                         |
| ------- | ------------------------------- |
| `stage` | How far the document has come.  |

The MyST form renders live in the MyST column specs.

Running headers and footers¶

header and footer give a page a running header or footer for the docutils writers that print one. A Sphinx build leaves them out, in its html and LaTeX builders alike, and so do ubc build html and ubc build pdf.

reStructuredText

Running headers and footers

.. header::

   The running header.

.. footer::

   The running footer.

Neither directive above prints anything here.

Neither directive above prints anything here.

MyST

```{header}
The running header.
```

```{footer}
The running footer.
```

Neither directive above prints anything here.

The MyST form renders live in the MyST headers and footers.

The highlight language¶

highlight sets the language of the literal blocks after it that name none: :: blocks, and code-block directives without an argument. Its :linenothreshold: option numbers every such block of at least that many lines. This specimen comes last on the page, so its language reaches nothing else here.

reStructuredText

The highlight language

.. highlight:: json

The block after it is highlighted as JSON::

   {"stage": "review", "pages": [1, 2]}

The block after it is highlighted as JSON:

{"stage": "review", "pages": [1, 2]}

MyST

```{highlight} json
```

The fence after it, which names no language, is highlighted as JSON:

```
{"stage": "review", "pages": [1, 2]}
```

The MyST form renders live in the MyST highlight language.

What ubCode highlights, and how, is in the code-block differences.