Relative links for images outside of presentation folder successfully preview, but break on render

[DallasNovakowski]

Not sure whether this belongs in quarto-cli

There seems to be an intentional shift in Quarto to use relative instead of absolute paths. In particular, these paths are relative to the .qmd file.

This may have produced a behaviour where images are not rendering properly if they lie outside of the same folder as the .qmd file. The images will correctly display as part of the automatic 'preview' in the source pane, but when the document is rendered, it returns the broken image icon in its place.

This is even the case if we were to use here::here or xfun::from_root. Using these functions work for sourcing external r scripts that follow the same directory structure, so seems to be something special with images. Using the execute-dir: project option does not seem to resolve the issue.

This issue has been brought up in the community postings by John Graves, and Andy Field.

I have copied and modified a Posit Cloud project from Jon Graves' post demonstrating the behaviour: https://posit.cloud/content/6847700. There are three qmd files: one that works (at the project root), and two that don't work (in the presentations folder).

This may be relevant to discussions in the renderthis package, although their concern seems to be placing rendered output in a separate directory, not sourcing files.

There also seems to be some discussion about making changes to how Quarto uses absolute vs. relative paths. The practice of specifying directories has also been discussed in quarto-r issue #81, where @cderv mentions the potentially evolving nature of how quarto handles outputs, inputs, and resources.

Resolving this issue will help those of us that might want to use a pool of shared images across many different reports, whether across different lectures, or different report formats (e.g., posters, manuscripts, presentations). Addressing this may also resolve quarto-r issue #94 posted by aputron.

[cderv]

There seems to be an intentional shift in Quarto to use relative instead of absolute paths. In particular, these paths are relative to the .qmd file.

I don't know if there is a shift as I think this has always be the case. When rendering a single document, the linked used in Markdown image for example will be relative to the rendered directory.

If you use tools to get it from a 'project' root (like xfun::from_root() or here::here()), this will correctly include a link to the images/ folder you gave in your root. Hovewer, the image will only be shown in HTML preview locally (or online in RStudio Cloud) if the server that serve the files is correctly started from root of your project too. And by default this is not the case: When you render a single document!

Try running server::http('.') from your RStudio project root, and navigate to the presentations in sub folder - images will show because now images/ folder is correctly accessible from the web server.

Without this, only the web server was started at the subfolder level for the HTML in the subfolder, and ../images does not exist in that case.

I hope this is clear.

Resolving this issue will help those of us that might want to use a pool of shared images across many different reports, whether across different lectures, or different report formats (e.g., posters, manuscripts, presentations).

When adopting this strategy, you need to really about projects for sources and outputs you produce.

First of all, you should really consider using Quarto projects if you want to manage your .qmd as a project. Currently in your RStudio cloud example, this is only a RStudio project, which is not the same.

When using Project, Quarto will know a .qmd file rendered is part of a project. And in that case, there are some nice options like path resolution from project, and preview from project root.

So if you add a _quarto.yml file with this content

project: 
  type: default

Now you can render the document in subfolder, and you should see image.

You should also be able to path like this starting with a /

![](/images/llama.png)

which means "relative to project root". Which avoid doing .. many times in some cases.

Using the execute-dir: project option does not seem to resolve the issue.

This should not be useful for image path IMO. This options for knitr is quite advanced, and allow to change the working directory from which knitr chunk are evaluated. If this is only a filepaths problem, using here::here() or xfun::from_root() should work ok.

This may be relevant to jhelvy/renderthis#73, although their concern seems to be placing rendered output in a separate directory, not sourcing files.

Yes this and other quarto-r issue is about output-file. Quarto will not allow to output in another directory not relative to the .qmd. If this is expected, it should be a two step process using wrapper function or scripts: Render the document then move the outputs.

Quarto projects of type Website or Manuscript will do some copying of results into a output-dir and it includes resources so that when deploying the output-dir, everything is at the right relative place from the HTML files.

So overall, try to use Quarto Projects, and then see if there is still some undesired behaviors.

Hope it helps.

[DallasNovakowski]

Amazing! Thank you.

I've left the original project as-is, but for any future readers, I've created an updated project that incorporates the fix https://posit.cloud/content/6927922, so you can see the change.

For novices like me:

Option 1: You can do the fix just as Cristophe says, create a new Quarto Project, and in the automatically-generated _quarto.yml file, put:

project:
  title: "my_project_name"
  type: default

Option 2: You can implement the fix without needing to start a Quarto Project from scratch. In your a RStudio Project, you can just click "new blank file" --> "text file", and name it _quarto.yml (which will automatically convert the icon), and place it at the project root. Put in the same project: information as option 1.