There are several problems with the *embed-preview.html:

• Plots are not shown, only alt text (because plot links to notebooks/200-code.embed_files/figure-html/fig-200-pxrd-diffractograms-output-1.png but the image actually lives at notebooks/200-code_files/figure-html/fig-200-pxrd-diffractograms-1.png, the directory 200-code.embed_files does not exist).
• page-layout: full is not obeyed, meaning the body is quite narrow which looks awful especially code chunks
• Author names, affiliations and date are repeated at the top of the body text
• First code chunk is empty (first actual chunk is number 2)

For reference, this was the case with the following manuscript stanza in YAML:

manuscript:
  article: index.qmd
  meca-bundle: false
  notebooks:
    - notebook: index.qmd
      title: Manuscript notebook
    - notebook: notebooks/200-code.qmd

Render button in RStudio Server

Render button in RStudio executes quarto preview index.qmd --to html --no-watch-inputs --no-browse and causes notebook sidebar to link to notebooks/200-code-preview.html, which does obey my format.html.page-layout: full, but figure captions lack numbers and so cross-refs are broken.

Keyboard shortcut in RStudio Server

Ctrl+Shift+b in RStudio executes quarto preview --render all --no-watch-inputs --no-browse and causes notebook sidebar to link to notebooks/200-code.embed-preview.html.

quarto render in CLI

quarto render (executed from CLI) causes notebook sidebar to link to notebooks/200-code.embed-preview.html (but not every time?).

quarto preview in CLI

quarto preview --render html --port 25598 --host 0.0.0.0 --no-browser (in the CLI) causes sidebar to link to notebooks/200-code.embed-preview.html.

Depends on YAML in a non-obvious way

But after commenting out the entire manuscript.notebooks list, the situation changes!
Now none of the above methods link to to the *embed-preview.html version - in fact, no such file is even rendered (only the *-preview.html is rendered).

• https://quarto.org/docs/manuscripts
• https://github.com/quarto-dev/quarto-cli/issues/11475
• https://github.com/quarto-dev/quarto-cli/discussions/6180

If your Quarto manuscript has notebooks, and in your manuscript you include or embed those notebooks in part or in whole, this triggers an renv "dependency discovery" step that may consume >100 seconds during quarto rendering, but seemingly only under certain conditions.

Over the last few days, I have tried to understand how to best avoid this slow "dependency discovery" step during rendering in my manuscript. Obviously it only affects your project if renv is activated. The whole issue can be side-stepped by commenting out the line source("renv/activate.R") in your ./.Rprofile file, but then no more renv and that did not work for me.

For testing purposes, I started from the RStudio manuscript template and always executed quarto render from the CLI (not using the Render button in RStudio, which usually executes with special flags depending on stuff).

Now, I might be missing the forest for all the trees, but I believe the "dependency discovery" step is triggered if we include the entire notebook into the manuscript (using either knitr child or quarto include made no difference), but not if we use quarto embed. That's the short of it.

Here are some more observations on what worked and did not work for those three cases.

knitr child approach

Not using any quatro includes or embeds except for the preamble-latex-html.qmd.

When rendered in RStudio the Notebook link points to <notebooks/200-code-preview.html>.
Math OK, figures in manuscript rendered OK, captions OK, cross-refs OK.

200-code notebook is rendered fullwidth as intended, title and authors OK. Fig caption text is OK.

• quarto render in bash compiled in 5m10.665s (mainly due to "renv dep" step).
• the manuscript includes any regular text from the notebook!
• figures in notebook are missing fig caption numbers (maybe because I used Quarto chunk settings?)

Fig caption number and text is OK in the manuscript in any case (note that captions
need to be set in the chunk in the manuscript - it is not carried over from the notebook).

quarto embed approach

Not using knitr child anywhere (replaced all of them by quarto include or embed).
quarto render in bash compiled in 1m18.055s - much better.

(Of course the fundamental limitation with embed is that no objects from the notebook's
namespace can be referenced in the manuscript).

Manuscript: math OK, figures and captions OK, cross-refs OK. Figure captions are carried over from the notebook. Notebook link points to <notebooks/200-code.embed-preview.html> (which is bad!) unless you set notebook-links: true (which is the default).

One problem remains in the notebook, fig captions missing numbers and thus cross-refs are broken. Not sure why.

quarto include approach

Behaves just like knitr child, c.f., above.

• slow render ("dependency discovery took 77 seconds during snapshot")
• manuscript includes regular text along with any chunks with echo=true etc., despite
  output=false, echo=false, include=false in the include command
• link to notebook in sidebar points to the embed version (which does not exist!)

comments

Clearly the notebook concept in Quarto manuscripts has some hard-coded behaviour and the documentation does not yet reflect all of this behaviour. I tried very hard to locate in the quarto source where this renv snapshot is triggered, but I was stumped. All I found was references to their test suite 1, 2, 3, 4.

It would have been nice if one could instruct quarto to entirely skip this renv dependency checking using a CLI flag or an ENV variable or some such. As it is now, running into this behaviour means potentially wasting so much time that there is really no point testing anything - all I want to do is just avoid the behaviour.

This is the message emitted during quarto render (duration may vary):

NOTE: Dependency discovery took 111 seconds during snapshot.
Consider using .renvignore to ignore files, or switching to explicit snapshots.
See `?renv::dependencies` for more information.

Creating an .renvignore file had no effect on this behaviour.
The renv::dependencies help page suggests switching from the default implicit dependency discovery to explicitly specifying your dependencies in a DESCRIPTION file (just like for an R package), but that would defeat the point of using renv for a manuscript like this in my opinion, so I did not go down that route.

Based on suggestions in a tangentially related renv issue I set RENV_WATCHDOG_ENABLED = FALSE in .Renviron, but that had no effect. Not sure why.

Updating from Quarto 1.5.57 (bundled with RStudio Server v2024.12.0+467) to Quarto v1.6.39 (DEB package) made no difference (as expected, nothing in the changelogs indicated this behaviour was considered).

I also changed a number of other properties, such as custom extension or not, global YAML settings, MathJax or not, but in the end none of that had any effect on whether the renv dependency discovery was triggered.

As far as I can tell, this dependency discovery is triggered by having quarto include or knitr child in the manuscript, but the length of the discovery also clearly depends on the number of R packages loaded by your document. Like I mentioned earlier - a possibility to disable this discovery entirely would be great.

For now, I will use quarto embed as it lead to fewest other problems.

sessionInfo

Behaviour as observed in latest stable quarto v1.6.39 and before that also v1.5.57.
System Ubuntu 22.04.5 GNU/Linux 5.15.0-124-generic x86_64.

$ quarto check
Quarto 1.6.39
[✓] Checking environment information...
      Quarto cache location: ~/.cache/quarto
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.4.0: OK
      Dart Sass version 1.70.0: OK
      Deno version 1.46.3: OK
      Typst version 0.11.0: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.6.39
      Path: /opt/quarto/bin

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

[✓] Checking LaTeX....................OK
      Using: Installation From Path
      Path: /usr/local/texlive/2023/bin/x86_64-linux
      Version: 2023

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

[✓] Checking Python 3 installation....OK
      Version: 3.10.12
      Path: /usr/bin/python3
      Jupyter: (None)

      Jupyter is not available in this Python installation.
      Install with python3 -m pip install jupyter

[✓] Checking R installation...........OK
      Version: 4.3.3
      Path: /opt/R/4.3.3/lib/R
      LibPaths:
        - ~/R/x86_64-pc-linux-gnu-library/4.3.3
        - /opt/R/4.3.3/lib/R/library
      knitr: 1.49
      rmarkdown: 2.29

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

Links

• https://bookdown.org/yihui/rmarkdown-cookbook/child-document.html
• https://bookdown.org/yihui/rmarkdown-cookbook/reuse-chunks.html
• https://zsmith27.github.io/rmarkdown_crash-course/lesson-6-child-documents.html
• https://yihui.org/knitr/options
• http://zevross.com/blog/2014/07/09/making-use-of-external-r-code-in-knitr-and-r-markdown
• https://github.com/quarto-dev/quarto-cli/discussions/11629