Conditional content

Three directives include their body only when a condition holds: only asks which build is running, by its tags; if asks a question of your variant data; and choose asks one such question once and takes the first branch that holds. A build leaves out what is excluded, while the editor preview keeps it visible, collapsed and greyed, so you can see it exists. A fourth, raw, passes its body to one output format only, untouched.

Builder tags (only)

only takes an expression of tags, joined with and, or and not, and parentheses. Every html build has the tags html, format_html and builder_html, and ubc build pdf has them too, because it renders the same pages. ubCode adds the tags listed in the top-level build_tags key of ubproject.toml, which a Sphinx build never reads. This site sets build_tags = ["ubc"], and its PDF is built with -c 'build_tags = ["ubc", "pdf"]', so the expressions below pick out each of its three builds.

reStructuredText

Builder tags

.. only:: html

   Every build of this site shows this line.

.. only:: not ubc

   You are reading the Sphinx build.

.. only:: ubc and not pdf

   You are reading the ``ubc build html`` build.

.. only:: pdf

   You are reading the ``ubc build pdf`` build.

Every build of this site shows this line.

You are reading the Sphinx build.

MyST

```{only} html
Every build of this site shows this line.
```

```{only} not ubc
You are reading the Sphinx build.
```

```{only} ubc and not pdf
You are reading the `ubc build html` build.
```

```{only} pdf
You are reading the `ubc build pdf` build.
```

The MyST form renders live in the MyST builder tags.

The specimen renders differently in each build, by design: each one shows the first line and the one line that names it.

Expression	Sphinx build	ubc build html	ubc build pdf
html	shown	shown	shown
not ubc	shown	left out	left out
ubc and not pdf	left out	shown	left out
pdf	left out	left out	shown

only decides what is shown, not what is parsed: both engines still read the body, so a construct one of them does not know is reported even inside an only that leaves it out. How an expression that cannot be parsed is handled, and what an excluded body can still define, are in the conditional content differences.

Variant conditions (if)

if takes a condition on your variant data, read through the var name. This site’s variant data sets stage to review, so the first block below is shown and the second is left out.

reStructuredText

Variant conditions

.. if:: var.stage == "review"

   Shown while the ``stage`` is ``review``.

.. if:: var.stage == "published"

   Left out until the ``stage`` is ``published``.

Shown while the stage is review.

MyST

```{if} var.stage == "review"
Shown while the `stage` is `review`.
```

```{if} var.stage == "published"
Left out until the `stage` is `published`.
```

The MyST form renders live in the MyST variant conditions.

The body can be any content, needs included: a need inside a false if is not created. What the preview shows for each, and what a condition may say, are in The if directive.

One branch of several (choose)

choose holds when branches, each with a condition, and an optional otherwise last. It includes the first when whose condition holds, or the otherwise when none does.

reStructuredText

One branch of several

.. choose::

   .. when:: var.stage == "draft"

      Drafting: nothing is reviewed yet.

   .. when:: var.stage == "review"

      In review: this branch is the one taken.

   .. otherwise::

      Published.

In review: this branch is the one taken.

MyST

````{choose}
```{when} var.stage == "draft"
Drafting: nothing is reviewed yet.
```

```{when} var.stage == "review"
In review: this branch is the one taken.
```

```{otherwise}
Published.
```
````

The MyST form renders live in the MyST branches.

choose, when and otherwise come from Sphinx-Needs 9.0 and later. What makes a choose invalid, and how the preview shows the branches not taken, are in The choose, when and otherwise directives.

Raw output for one format (raw)

raw passes its body, unchanged and unchecked, to the output formats its argument names: html reaches every HTML build, and nothing else. Treat it as markup you are responsible for.

reStructuredText

Raw HTML

.. raw:: html

   <p>Press <kbd>Ctrl</kbd> + <kbd>S</kbd> to save the page.</p>

Press Ctrl + S to save the page.

MyST

```{raw} html
<p>Press <kbd>Ctrl</kbd> + <kbd>S</kbd> to save the page.</p>
```

The MyST form renders live in the MyST raw output.

A PDF is not an HTML build, so ubc build pdf prints nothing for this specimen, as a Sphinx LaTeX build does.

The raw role, derived for a format with the role directive, the :file: option, and the switch that turns raw content off, are in Raw content.