echo and output options not working in manuscript companion notebooks

[jpvelez]

Hi there,

Very excited about the new manuscript project type. I think I may have encountered a bug, however. I have a companion.qmd file with R code sitting alongside index.qmd. When I render the project with knitr and view index.html, the companion notebook is automatically displayed in the "Notebooks" section of the sidebar of my rendered index.md. So far, so good.

The problem is that output: false not echo: false in companion.qmd don't appear to be working, either in the YAML header or within individual code blocks. I set them to false and both the code and the code output still appear in the rendered companion.html file. (Note that this file has a blue bar at the top that says "Back to Article", it isn't rendered separately.)

output and false options work just fine in the index.md article, however. I'm using quarto version 1.4.549, using the VSCode extension (though I doubt that matters).

Apologies is if this is posted in the wrong repo! Would love any help I can get.

[dragonstyle]

Glad you're taking manuscripts out for a spin - thanks for taking the time to open this!

• I've transferred this to the quarto-cli repo (since it isn't specific to the Quarto VS.Code extension)

• Currently, we think of this as 'by design'. The way we currently envisioned the notebooks being used in manuscripts, they are intended to be companions to the main article, and the rendered views are designed to show their source code and outputs (as if the viewer was actually looking at a notebook containing the code and execution results). As a result, we always show the code cells, outputs, and so on. They're very often used to provided embedded content within the article (which links back to the rendered notebook as well).

I'd be curious to hear about how you're envisioning using them and how you see controlling the cell options would be useful if you don't mind sharing a bit?

[jpvelez]

Thanks for getting back to me so quickly!

The idea of a companion that shows code and outputs makes total sense. The problem I'm running into is that sometimes things can get noisy.

For instance, this code:

Renders like this:

I'd love to be able to selectively silence the output of certain cells to quiet them down.

I could see a use case for supporting block-level echo in companion notebooks too: the "production" code you use to generate results that you embed in the article table could feature uninteresting, technical throat-clearing at the beginning, like talking to an API, and you may want the companion notebook to be friendlier to readers, so you may want to hide certain things.

Going further, I could see companion notebooks replacing methodology sections if they supporting toggling the code on and off: you would walk people through your analysis step by step, and people who can't read the code could follow along anyway.

Another use case for code toggling might be adding an "exploratory data analysis" notebook that does further analysis that doesn't get embedded into the main report (a use case that is theoretically supported now), but you want this supplemental analysis to be consumable by people without having to read the code.

[mcanouil]

@jpvelez Could you edit your post to share code as plain text? Screenshots cannot be read by screen readers (and you did not set a meaningful alternative text), code from screenshots cannot be copied, etc.
Thank you for your understanding.

---

You can share a self-contained "working" (reproducible) Quarto document using the following syntax, i.e., using more backticks than you have in your document (usually four ````).
See https://quarto.org/bug-reports.html#small-is-beautiful-aim-for-a-single-document-with-10-lines.

If you have multiple files (and it is absolutely required to have multiple files), please share as a Git repository.

````qmd
---
title: "Reproducible Quarto Document"
format: html
engine: knitr
---

This is a reproducible Quarto document using `format: html`.
It is written in Markdown and contains embedded R code.
When you run the code, it will produce a plot.

```{r}
plot(cars)
```

![A placeholder image](https://placehold.co/600x400.png)

The end.
````

Additionally and if not already given, please share the output of quarto check within a code blocks (i.e., using three backticks ```txt), see https://quarto.org/bug-reports.html#check.

[mapi1]

The behavior mentioned, that cell options are not respected in companion notebooks, can be reproduced when rendering the example from the docs with either the current stable or pre-release.
In that repository, the rendered version of the companion notebook Data Screening looks like:

But the re-rendered version looks like:

Adding other options like #| echo: false have no effect as described above.

The rendered version of the article notebook is correct, though.

Other than that, it's a blast to work with quarto manuscripts, thanks for that!

Additional info:

(base) marius@host:~/Documents/manuscript-template-vscode$ quarto check
Quarto 1.5.16
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.1.11: OK
      Dart Sass version 1.69.5: OK
      Deno version 1.37.2: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.5.16
      Path: /opt/quarto/bin

[✓] Checking tools....................OK
      TinyTeX: (not installed)
      Chromium: (not installed)

[✓] Checking LaTeX....................OK
      Using: Installation From Path
      Path: /usr/bin
      Version: 2023

[✓] Checking basic markdown render....OK

[✓] Checking Python 3 installation....OK
      Version: 3.9.16 (Conda)
      Path: /home/marius/micromamba/bin/python
      Jupyter: 5.3.0
      Kernels: python3, julia-1.9, inversion_dev.venv, julia-1.8

[✓] Checking Jupyter engine render....OK

[✓] Checking R installation...........OK
      Version: 4.3.1
      Path: /usr/lib/R
      LibPaths:
        - /home/marius/R/x86_64-pc-linux-gnu-library/4.3
        - /usr/local/lib/R/site-library
        - /usr/lib/R/site-library
        - /usr/lib/R/library
      knitr: (None)
      rmarkdown: (None)

      The knitr package is not available in this R installation.
      Install with install.packages("knitr")
      The rmarkdown package is not available in this R installation.
      Install with install.packages("rmarkdown")

[dragonstyle]

It is currently going to be difficult to make per-cell options for echo work - the case you outline above completely makes sense, but going to take time to get to it. In the meantime, one workaround to explore would be using code-fold: true (either globally or per cell). This may get things closer to what you'd like, including the code in notebook, but not displaying it by default.

Ideally, there would be a version of this that would have the benefit of the all code being present and transparent, but not being distracting or confusing to readers (if this isn't already enough).

[udurraniAtPresage]

One possibility is to use suppressPackageStartupMessages(library(tidyverse)). Not ideal though.

[mcanouil]

@udurraniAtPresage For the tidyverse loading, the right way is: options(tidyverse.quiet = TRUE).
Note also that library() has quietly and verbose arguments.