Document path expectations for non-project documents

[ttimbers]

What is wrong

When the render button in RStudio is used to render a qmd file to .html the images (whether they are embedded via Markdown or with R code via knitr::include_graphics) do not display in the HTML preview in the viewer pane. However the images are visible in the notebook/.qmd in the editor, and when the .html file is opened in a web browser. See screenshots:

What is the expected behaviour

Any images/figures correctly embedded with either Markdown or with R code via knitr::include_graphics should be visible in the HTML preview in the viewer pane.

Environment information

• Mac (Version 13.4 (22F66))
• RStudio (Version 2023.12.1+402 (2023.12.1+402))
• R (version 4.3.2)
• Quarto (version 1.3.450)

[chendaniely]

I narrowed down the issue as a reprex in this repo: https://github.com/chendaniely/2024-02-15-quarto_preview_repex

quarto preview is showing a broken image when the qmd file is in a subfolder from the root of the repository, and the image it is referencing is in a different subfolder. You need to turn the directory into a quarto project by creating an empty _quarto.yml

Recreated from that reprex repo readme:

1. If you open this_works.qmd and click the preview button in VSCode or Render button in RStudio, the resulting html file in the viewer pane and output html render as expected.
2. If you open the analysis/no_work.qmd file and click the preview or render button, you get a broken image link
3. you need to create a top-level _quarto.yml file to turn the entire folder into a quarto project.
   • you also need to make sure any existing quarto preview session is closed and re run the command

the quarto projects documentation only talks about redirecting output to a different directory. It does not mention requiring a project file to reference images from a different directory (https://quarto.org/docs/projects/quarto-projects.html).

I'm not sure if we need to be more explicit about quarto document documentation assumes everything the same directory, and other workflows should use quarto projects.

This can all be seen in VSCode and RStudio, so it seems like it's specific to quarto preview

[cderv]

Thanks both of you. I'll move this to quarto repo as it seems related to quarto preview and not the R package quarto.

We'll look into it.

[cscheid]

the quarto projects documentation only talks about redirecting output to a different directory. It does not mention requiring a project file to reference images from a different directory (https://quarto.org/docs/projects/quarto-projects.html).

It's not about different directories, it's about not allowing references to the parent directory. We don't allow references outside of the "root directory of the document". For projects, that's the project root. For single documents, that's the folder where the document lives. This is by design, so that the set of resources available to a document doesn't include the entire computer where the document is being generated (That would make reproducibility a lot more challenging than it already is)

[ttimbers]

But what is strange @cscheid is that everything else but the preview works without the _quarto.yml, and the docs do not (at least to me) make it clear you need to add this. What I mean is that the rendered document itself is fine when clicking Render in RStudio from a document that lives in a subfolder, and references folders in the parent folder. And running quarto ... from the command line from the project root, also renders the document fine. So this issue/feature is really tied to the preview.

I would argue, that having a directory structure where the report references folders in the parent directory is very common in well organized data science projects (lots of well known books, blogs and tutorials suggest this), and in other projects as well. So either the docs need to make this clearer, or preview should perhaps work as the Render button works in RStudio.

[cscheid]

I would argue, that having a directory structure where the report references folders in the parent directory is very common in well organized data science projects (lots of well known books, blogs and tutorials suggest this), and in other projects as well.

I can't speak for other projects or their documentation. But in Quarto, if you want to use references to parent directories, you need to create a project. This is, again, by design and for a good reason.

And running quarto ... from the command line from the project root, also renders the document fine. So this issue/feature is really tied to the preview.

That might actually be a quarto bug. It shouldn't render fine. But, without a concrete reproducible example for us to see, it's hard to say. I'm additionally confused by your usage of "project root". Is this or is this not a project document? (I think you mean an "rstudio project"?)

[ttimbers]

@chendaniely already shared a reprex here: https://github.com/chendaniely/2024-02-15-quarto_preview_repex

I am using "project root" to mean the root directory of the project in its entirety. For example, in the GitHub repository above, that would be the 2024-02-15-quarto_preview_repex directory.

[cscheid]

@chendaniely already shared a reprex here: https://github.com/chendaniely/2024-02-15-quarto_preview_repex

Ok I was probably missing the context, but I'm guessing you two are working together on this? If that's the case, I apologize. For what's worth, it helps us to know when that's the case: we usually ask two separate people to provide two separate reprexes because it's often not the same issue!

[ttimbers]

Yes we are working together on this. Apologies that was not clear.