Provide a helper function to create metadata yaml block in document body

[cderv]

Related to #160

cc @kmasiello

Example

---
title: "Some title"
format: html
---

```{r}
admin <- TRUE
```


```{r}
#| output: asis
cat(
  "---",
  paste0("admin: ", ifelse(admin, "true", "false")),
  "---",
  sep = "\n"
)
```

Is this document for admin: {{< meta admin >}}


::: {.content-visible when-meta="admin"}
If so, then this should be visible as it is only `when-meta="admin"`
:::

::: {.content-hidden when-meta="admin"}
Hum... It seems you are not admin..
:::

This is quite long to write, so it could use a helper

Using inline R code

---
title: "Some title"
format: html
---

```{r}
admin <- TRUE
```


```{r}
write_meta <- function(meta) {
  handlers <- list(logical = function(x) {
        value <- ifelse(x, "true", "false")
        structure(value, class = "verbatim")
    })
  res <- yaml::as.yaml(meta, handlers = handlers)
  knitr::asis_output(paste0("---\n", res, "---\n"))
}
```


`r write_meta(list(admin = TRUE))`


Is this document for admin: {{< meta admin >}}


::: {.content-visible when-meta="admin"}
If so, then this should be visible as it is only `when-meta="admin"`
:::

::: {.content-hidden when-meta="admin"}
Hum... It seems you are not admin..
:::

Or using a cell with option

---
title: "Some title"
format: html
keep-md: true
---

```{r}
admin <- TRUE
```


```{r}
write_meta <- function(meta) {
  handlers <- list(logical = function(x) {
        value <- ifelse(x, "true", "false")
        structure(value, class = "verbatim")
    })
  res <- yaml::as.yaml(meta, handlers = handlers)
  knitr::asis_output(paste0("---\n", res, "---\n"))
}
```

```{r}
#| echo: false
#| output: asis
write_meta(list(admin = TRUE))
```

Is this document for admin: {{< meta admin >}}


::: {.content-visible when-meta="admin"}
If so, then this should be visible as it is only `when-meta="admin"`
:::

::: {.content-hidden when-meta="admin"}
Hum... It seems you are not admin..
:::

Food for thoughts...

[cderv]

More thoughts:

I wonder if we could make that more transparent and internal to Quarto so that a user would not have to write the meta value.

Same way a user don't have to write the HTML dependencies in header - knitr and quarto will do it.

We could maybe leverage the knit_meta field in knitr to pass information about which list object is considered to be quarto metadata so that quarto itself will add them to the rest of metadata. 🤔

POC of what could work to write all meta collected at once

---
title: "Some title"
format: html
keep-md: true
---



Example of helpers

```{r}
as_quarto_meta <- function(meta) {
  yaml_quarto_meta <- structure(meta, class = "quarto_yaml_meta")
  knitr::asis_output(list(), meta = list(yaml_quarto_meta))
}
```

Computing a value in R 

```{r}
admin <- TRUE
```

Setting it as a meta to us

```{r}
# add meta
as_quarto_meta(list(admin = admin))
```


Is this document for admin: {{< meta admin >}}


::: {.content-visible when-meta="admin"}
If so, then this should be visible as it is only `when-meta="admin"`
:::

::: {.content-hidden when-meta="admin"}
Hum... It seems you are not admin..
:::

```{r}
as_quarto_meta(list(userid = "abc"))
```


simulate quarto rendering to handle knit_meta as rmarkdown would handle latex dependencies and html dependencies

```{r}
write_meta <- function() {
  quarto_meta <- rmarkdown:::knit_meta_reset("quarto_yaml_meta")
  if (!length(quarto_meta)) return()
  handlers <- list(logical = function(x) {
        value <- ifelse(x, "true", "false")
        structure(value, class = "verbatim")
  })
  res <- yaml::as.yaml(unlist(quarto_meta, recursive = FALSE), handlers = handlers)
  knitr::asis_output(paste0("---\n", res, "---\n"))
}

write_meta()
```

Integrating this logic in Quarto directly would not pass by a writing on meta as yaml in the doc, but would be passed directly to quarto...

Not sure it worth it - only if we want to have the exact same logic maybe in jupyter if similar tooling as HTML deps come out one day 🤔

[kmasiello]

See rich-iannone/quarto-email#9 for a prime use case, but smoothing out these edges will be relevant beyond conditional emails.

[cderv]

@rich-iannone can you look at the POC idea above (#137 (comment)) ?

I believe the function offered would solve the issue right ?

this R package quarto could provide a function to write simply any list as a YAML block in Markdown, but I wonder if the meta idea could be even better for user experience.

Even quarto itself could retrieve the meta defined by any R function and do the YAML metadata addition. We can discuss live too.

Thanks

[cderv]

Listing another usage of this: A good workflow to provide a solution in Quarto for previous !expr logic.

Example:

• about page doesn't allow computation in the YAML header quarto-cli#5308

[mcanouil]

A slight modification of the proof of concept shared earlier but more versatile:

as_quarto_meta <- function(...) {
  if (is.list(..1) && !inherits(..1, "data.frame")) {
    meta <- ..1
  } else {
    meta <- list(...)
  }
  class(meta) <- "quarto_yaml_meta"
  knitr::asis_output(list(), meta = list(meta))
}

which allows:

my_generated_meta <- list(firstname = "John", lastname = "Doe")
as_quarto_meta(my_generated_meta)
# or
as_quarto_meta(firstname = "John", lastname = "Doe")

Code

---
title: "Some title"
format: html
keep-md: true
---



Example of helpers

```{r}
as_quarto_meta <- function(...) {
  if (is.list(..1) && !inherits(..1, "data.frame")) {
    meta <- ..1
  } else {
    meta <- list(...)
  }
  class(meta) <- "quarto_yaml_meta"
  knitr::asis_output(list(), meta = list(meta))
}
```

Computing a value in R 

```{r}
admin <- TRUE
```

Setting it as a meta to us

```{r}
# add meta
as_quarto_meta(admin = admin)
```


Is this document for admin: {{< meta admin >}}


::: {.content-visible when-meta="admin"}
If so, then this should be visible as it is only `when-meta="admin"`
:::

::: {.content-hidden when-meta="admin"}
Hum... It seems you are not admin..
:::

```{r}
as_quarto_meta(userid = "abc", admin = FALSE)
```

- `userid`: {{< meta userid >}}
- `admin`: {{< meta admin >}}

```{r}
my_generated_meta <- list(firstname = "John", lastname = "Doe")
as_quarto_meta(my_generated_meta)
```

- `firstname`: {{< meta firstname >}}
- `lastname`: {{< meta lastname >}}


simulate quarto rendering to handle knit_meta as rmarkdown would handle latex dependencies and html dependencies

```{r}
write_meta <- function() {
  quarto_meta <- rmarkdown:::knit_meta_reset("quarto_yaml_meta")
  if (!length(quarto_meta)) return()
  handlers <- list(logical = function(x) {
        value <- ifelse(x, "true", "false")
        structure(value, class = "verbatim")
  })
  res <- yaml::as.yaml(unlist(quarto_meta, recursive = FALSE), handlers = handlers)
  knitr::asis_output(paste0("---\n", res, "---\n"))
}

write_meta()
```