feature: control conditional content with boolean metadata

[cscheid]

This closes #5707.

cc @aronatkins, @dragonstyle, @jjallaire

Aron: the feature is intentionally quite narrow; we want to avoid things degenerating into a turing-complete expression language. This means each conditional block can only check the value of a single metadata entry, and only checks against true and false values.

The included test document shows the syntax.

It's also worth noting that changing the metadata on a Lua filter currently will not work. This was on purpose, so that we can eventually do dependency analysis statically without having to run Pandoc.

[allefeld]

Exactly what I was looking for! But it doesn't seem to have been released? At least it doesn't work for me in 1.3.450.

---
debugging: false
---

:::::: {.content-visible when-meta="debugging"}

::::::

[cderv]

@allefeld This is a 1.4 feature - so you need 1.4.119 or above

[allefeld]

I'll wait for that to be released officially then.

[cscheid]

(I realize now that I forgot to add a 1.4 changelog entry for this. I apologize for the confusion)

[AntheSevenants]

I use this feature to generate output for typesetting purposes for articles (where figures are omitted and replaced with messages like PLACE FIGURE 1 HERE). I found that omitting a figure using conditional formatting causes it to no longer work in cross-references (which is to be expected). However, I'm unable to define a second figure with the same ID for the reverse condition, since this leads to a "Duplicate chunk label".

Any pointers as to what I could do? I'm fine with either behaviour, both having both at the same time is very confusing. Thanks!

::: {.content-hidden when-meta="manuscript"}

```{r #fig-foo}
plot_function()
```

:::

::: {.content-visible when-meta="manuscript"}

**PLACE FIGURE 1 HERE**

```{r #fig-foo}
nothing()
```

:::

[cderv]

@AntheSevenants see about #5161 (comment) as it may help (defining the id once for difference content based on conditional)

[AntheSevenants]

@cderv Thanks for your response! I played around with the syntax, and got it to work (somewhat). If I separate the figure ID and caption, the Figure label and caption appear separately:

:::: {#fig-foo}

::: {.content-hidden when-meta="manuscript"}

```{r}
#| fig-cap: Figure Caption
plot_function()
```

:::

::: {.content-visible when-meta="manuscript"}

**PLACE FIGURE 1 HERE**

:::

::::

I can fix this by moving the figure caption into the div definition:

:::: {#fig-foo fig-cap="Figure Caption"}

::: {.content-hidden when-meta="manuscript"}

```{r}
plot_function()
```

:::

::: {.content-visible when-meta="manuscript"}

**PLACE FIGURE 1 HERE**

:::

::::

However, now the caption still appears under "PLACE FIGURE 1 HERE", and ideally I'd have the caption not appear at all when meta-manuscript is true. I take that this is currently not possible? This is a very niche case, so I completely understand if this is beyond the current feature set. In any case, thank you! This is really cool stuff.

[cderv]

I take that this is currently not possible? This is a very niche case, so I completely understand if this is beyond the current feature set.

This could probably be possibly using only knitr and params for example. (when-meta is only a quarto thing); This would mean only working for R engine document leveraging only execution feature from knitr (not Quarto)

Disclaimer: Advanced usage only, and tied to knitr but still works - No quarto warranty whatsoever though.

---
title: "test"
format: 
  html: default
params:
  manuscript: false
---

See this plot:

```{r}
#| eval: !expr params$manuscript
#| echo: false
#| label: fig-plot
#| fig-cap: Figure Caption
plot(cars)
```

```{asis, echo = !params$manuscript}
::: {#fig-plot}
**PLACE FIGURE 1 HERE**
:::
```

See @fig-plot

If you want the caption in both plot and placeholder, you may be looking for this syntax instead

---
title: "test"
format: 
  html: default
params:
  manuscript: true
---

See this plot:

::: {#fig-plot}

```{r}
#| eval: !expr params$manuscript
#| echo: false
plot(cars)
```

```{asis, echo = !params$manuscript}
**PLACE FIGURE 1 HERE**
```

Figure Caption
:::

See @fig-plot

Some resources

• About the special asis knitr engine
• !expr is knitr only from the yaml R package used by knitr - not recommended as quite advanced too but can be useful, and required to evaluate R expression as YAML values. Using historic chunk option syntax works also with knitr when using Quarto.
• About new cross reference system for 1.4 : https://quarto.org/docs/prerelease/1.4/crossref.html, including Figure caption positioning.

Hope it helps as workaround until we try to improve pre-execution processing 🤔