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

[thothal]

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

```{r chart-chunk}
plot_ly(x = 1, y = 10, type = "bar")
```
> Text not shown if chunk `clean-up-chunk` is added after this chunk

```{r clean-up-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:

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]

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]

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]

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]

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.