Quarto images don't display in preview when using absolute path

[ronblum]

Bug description

Quarto images don't display in preview when using absolute path. The absolute path is being treat as relative to the local directory.

Steps to reproduce

This can all be done in RStudio, but I'm leaving it out because the behavior is with Quarto. Discovered while working on RStudio issue rstudio/rstudio/issues/12690.

1. Create a new project: quarto create project as a default and with the name quarto_image
2. cd quarto_image
3. mkdir images
4. Place an image file called somepath.png in the images directory.
5. Edit the Quarto_image.qmd to contain the following

---
title: "Quarto Image"
---

Start Relative Path ![](images/somepath.png)End Relative Path

Start Absolute Path ![](/Users/ronblum/Projects/Testing/quarto_image/images/somepath.png) End Absolute Path

but change the second image reference to the image file's absolute page.

6. quarto preview Quarto_image.qmd
   • The preview is opened in a web page.
   • The image with the relative path is displayed.
   • The image with the broken path is broken.

Expected behavior

Both images get displayed.

Actual behavior

When the web page is opened:
- The image with the relative path is displayed.
- The image with the broken path is broken.

Looking at the generated page's source, the absolute path is getting set as relative to the local directory.

<p>Start Relative Path <img src="images/somepath.png" class="img-fluid">End Relative Path</p>
<p>Start Absolute Path <img src="./Users/ronblum/Projects/Testing/quarto_image/images/somepath.png" class="img-fluid"> End Absolute Path</p>

In the terminal in which Quarto is running:

Output created: Quarto_image.html

Watching files for changes
Browse at http://localhost:3952/Quarto_image.html
  /Users/ronblum/Projects/Testing/quarto_image/images/somepath.png (404: Not Found)

Your environment

Quarto 1.4.429
R 4.3.1
MacOS 14.1
RStudio Desktop Pro 2023.12.0-daily+221.pro12 (but reproduced outside of RStudio)

Quarto check output

[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.1.8: OK
      Dart Sass version 1.55.0: OK
      Deno version 1.33.4: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.4.429
      Path: /Applications/RStudio-2023.12.0-daily-212.app/Contents/Resources/app/quarto/bin

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

[✓] Checking LaTeX....................OK
      Using: TinyTex
      Path: /Users/ronblum/Library/TinyTeX/bin/universal-darwin
      Version: 2023

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

[✓] Checking Python 3 installation....OK
      Version: 3.11.4
      Path: /usr/local/opt/python@3.11/bin/python3.11
      Jupyter: (None)

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

[✓] Checking R installation...........OK
      Version: 4.3.1
      Path: /Library/Frameworks/R.framework/Resources
      LibPaths:
        - /Users/ronblum/Library/R/x86_64/4.3/library
        - /Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/library
      knitr: 1.44
      rmarkdown: 2.25

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

[mcanouil]

This is not a bug.
Quarto resolves path within a project in the goal of reproducibility.
Using leading / means root of the Quarto project.
This is described in several places such as https://quarto.org/docs/websites/website-tools.html#site-resources.

[ronblum]

Thanks! I'll update rstudio/rstudio/issues/12690 to reflect that this is by design.

[cswingle]

I see this is closed and merged as part of pull #13838, but I don't understand the logic behind applying this rule when the Quarto document is not part of a project. Using a leading slash has a long standing meaning: absolute path; and having to make symlinks or something in order to put figures at the same level as the Quarto document (even within a project, honestly) seems surprising to me.

[mcanouil]

I see this is closed and merged as part of pull #13838,

@cswingle Sorry I don't understand what you are referring to. It seems you are referencing things that are not in Quarto.
The thread was about RStudio IDE and how it should account for Quarto design choices.

One of the goals of Quarto is to have reproducible documents/projects. Paths outside the "project" is clearly a reproducibility breaker.
you might disagree with the reproducibility goal and the design choices that come with it but this is not going to change.

FYI: A Quarto document is treated as a project since 1.5.

[cswingle]

@mcanouil Understood re Quarto docs being their own “project”. I was surprised by this new behavior when rendering a document with 1.5 that worked fine under 1.4, and the idea that an absolute path would be changed to be relative to the Quarto document seems to break with long standing Unix tradition. Thanks for your reply and clarification.

[cscheid]

rendering a document with 1.5 that worked fine under 1.4,

Using a leading slash has a long standing meaning

Quarto document seems to break with long standing Unix tradition

Your comment seems to imply a few inaccurate things. Just to be clear, this is behavior that we've used since Quarto 1.0, as @mcanouil pointed out in the documentation.

as far as "Unix tradition is concerned": note two things:

• Quarto works in systems other than Unix, where that tradition wouldn't be defined
• the tradition exists to resolve paths from the root of the (in Unix) root directory tree. Quarto does, in fact, attempt to preserve this tradition, resolving the path from where it makes the most sense; the root of the project or document.

I promise you we're aware of Unix traditions. I would like to suggest that you might not be taking all the considerations we did into account, and to keep that in mind in the future. Thanks!

[cswingle]

@cscheid Using Quarto 1.4, a figure path that starts with a slash is treated as an absolute filesystem path and a single-file Quarto document renders successfully to PDF. In 1.5, a dot is prepended to the path to make the path relative to the location of the quarto document and TeX cannot find the file. I do understand the rationale for this, but it is a recent change and was a surprise to me. I expect it might be a surprise to others that are used to a leading slash (or drive letter in Windows) meaning "root" in a different sense than "root of the project or document". It sounds like this is a decided issue and the definition of paths and their meaning in the context of Quarto isn't going to change. Fair enough. I meant no disrespect, I was merely trying to explain why this behavior was a surprise to me.

[cscheid]

Using Quarto 1.4, a figure path that starts with a slash is treated as an absolute filesystem path and a single-file Quarto document renders successfully to PDF

That's the 1.4 behavior for single-file renders. In projects that already wasn't the case, and that was not only for "book" projects. It was also the case for default and website projects.

I was merely trying to explain why this behavior was a surprise to me.

Understood. We should have done a better job at documenting the change. We made the behavior more uniform; "default" and "website" projects already behaved in this way; now single-file renders also do.

It sounds like this is a decided issue and the definition of paths and their meaning in the context of Quarto isn't going to change.

That's correct; it's how Quarto "always" behaved and intended to behave, aside from this (admittedly popular) "corner" case.

I'll also note that this isn't just a Quarto behavior: other typesetting systems work the same way. Consider typst. Quarto supports emitting Typst code, but here you can see the pure-Typst behavior:

[cderv]

That's the behavior for single-file renders.

@cscheid I believe this is not the case anymore since 1.5. My understanding of what @cswingle is reporting is that for single file project render the behavior has changed.

Quick example of this is

---
title: test
format: html
embed-resources: true
---

Some content

![](/tmp/elephant.png)

I am using embed-resources to get the pandoc's warning

And with image from our website

cd /tmp
curl -O https://quarto.org/docs/authoring/elephant.png
cd 

Single doc not in a project. Calling quarto render on the file

• Quarto 1.5 will show us a [WARNING] Could not fetch resource ./tmp/elephant.png and no image in doc. See the ./tmp
• Quarto 1.4 will show no warning and image is correctly embeded.

I believe this behavior is due to the fact Single file render has now since 1.5 some concept of single file project. And so it inherits this behavior from project.

I thought this was expected change, but reading you I am unsure, so I preferred to share in case we should open an issue about that.

[cscheid]

That's the behavior for single-file renders.

@cscheid I believe this is not the case anymore since 1.5.

I meant in 1.4; edited now to clarify.

[cderv]

All good then ! Thanks for the clarification - I was also in doubt 😅