Notes are silently dropped if a no-output producing chunk is inserted

thothal commented 7 months ago

Disclaimer

I previously asked this question on SO to check whether this behavior is maybe intentional and got a workaround as a solution, but I am still not sure whether this behavior is really intentional.

Problem

When adding a chunk, which produces no output (for example to close a database connection), after a chunk with notes, the notes ( added via >) disappear.

Reprex

---
title: "Clean Up Chunk is Bad"
output:
  flexdashboard::flex_dashboard:
    orientation: rows
---

```{r}
library(plotly)

Row

A Chart

plot_ly(x = 1, y = 10, type = "bar")

Text not shown if chunk clean-up-chunk is added after this chunk

### Remove (or not include) this chunk altogether to make the note re-appear again
### Usage: for example to close a db connection
## dbDisconnect(con)


The text is by the way in the final HTML but not rendered properly:

![image](https://github.com/rstudio/flexdashboard/assets/30824940/c5ffd7d2-1ed0-4afe-901d-d93c8c14da51)

Workaround is to add `include = FALSE` to `clean-up-chunk`.

### Session Info

─ Session info ──────────────────────────────────────────────────────────────────────────────────── setting value version R version 4.2.2 (2022-10-31 ucrt) os Windows 10 x64 (build 19045) system x86_64, mingw32 ui RStudio language EN collate German_Germany.utf8 ctype German_Germany.utf8 tz Europe/Berlin date 2024-02-16 rstudio 2023.03.0+386 Cherry Blossom (desktop) pandoc 2.19.2 @ C:\Users\tthaler\AppData\Local\Programs\RStudio\RESOUR~1\app\bin\quarto\bin\tools\pandoc.exe

─ Packages ──────────────────────────────────────────────────────────────────────────────────────── package version date (UTC) lib source bslib 0.6.1 2023-11-28 [1] CRAN (R 4.2.3) cachem 1.0.8 2023-05-01 [1] CRAN (R 4.2.3) cli 3.6.2 2023-12-11 [1] CRAN (R 4.2.3) digest 0.6.34 2024-01-11 [1] CRAN (R 4.2.3) evaluate 0.23 2023-11-01 [1] CRAN (R 4.2.3) fastmap 1.1.1 2023-02-24 [1] CRAN (R 4.2.3) flexdashboard 0.6.2 2023-08-11 [1] CRAN (R 4.2.3) htmltools 0.5.7 2023-11-03 [1] CRAN (R 4.2.3) jquerylib 0.1.4 2021-04-26 [1] CRAN (R 4.2.2) jsonlite 1.8.8 2023-12-04 [1] CRAN (R 4.2.3) knitr 1.45 2023-10-30 [1] CRAN (R 4.2.3) lifecycle 1.0.4 2023-11-07 [1] CRAN (R 4.2.3) R6 2.5.1 2021-08-19 [1] CRAN (R 4.2.2) rlang 1.1.3 2024-01-10 [1] CRAN (R 4.2.3) rmarkdown 2.25 2023-09-18 [1] CRAN (R 4.2.3) rstudioapi 0.15.0 2023-07-07 [1] CRAN (R 4.2.3) sass 0.4.8 2023-12-06 [1] CRAN (R 4.2.3) sessioninfo 1.2.2 2021-12-06 [1] CRAN (R 4.2.2) systemfonts 1.0.5 2023-10-09 [1] CRAN (R 4.2.3) xfun 0.41 2023-11-01 [1] CRAN (R 4.2.3) ───────────────────────────────────────────────────────────────────────────────────────────────────

gadenbuie commented 7 months ago

Thanks for asking @thothal!

Workaround is to add include = FALSE to clean-up-chunk.

Rather than call this a workaround, I'd say it's the solution. In flexdashboard, chunks are automatically repurposed in certain ways. If you want to run code without affecting the appearance of the dashboard, then you need to use include = FALSE to ensure flexdashboard doesn't try to include the code chunk in the dashboard.

thothal commented 7 months ago

Thanks for the feedback. A fair point, but I guess it deserves to be explicitely mentioned in some of the docs then, b/c it took me by surprise and quite some debugging sessions to even find out when the notes disappear.

I like to split up code, and not all chunks produce an output. I was totally not aware that you must not include non output chunks, b/c besides the issue with the notes I did not see any issue with that up to now.

My take away is to not include these non output chunks in the future, and recommend to document that somewhere, such that others don't fall in the same trap.

gadenbuie commented 7 months ago

Great point! Do you remember where you looked while debugging? It's hard to know where to put these kinds of things in the docs.

thothal commented 7 months ago

Well, I did read the documentation at https://pkgs.rstudio.com/flexdashboard/articles/using.html quite thoroughly and any section title Non output producing chunks would have caught my attention 😉

So I guess any hint there would be useful, because unlike for 'normal' packages where I read the builtin help pages, I usually refer exclusively to the published articles for rmarkdown styles.

rstudio / flexdashboard