Why does "embed-resources: true" require relative image paths?

[blacksqr]

Today I added "embed-resources: true" to a working website project, and the render failed. It turned out to be because I had an "about:" section in my index.qmd metadata, with an image setting of the form: "/img/about.jpg". The error looks like:

pandoc: /img/about.jpg: withBinaryFile: does not exist (No such file or directory)

If I change the setting to: "img/about.jpg" the render succeeds.

The doc says "Scripts, images, and stylesheets at absolute URLs will be downloaded". Where is the renderer trying to retrieve "/img/about.jpg" from? From an absolute path on my filesystem? If so, shouldn't the renderer refrain from doing this unless there is a fully-specified URI such as "file///img/about.jpg"?

IMO there shouldn't be a need for me to diagnose why my render failed and then to change a lot of existing YAML settings (and possibly move a lot of files) if I'm just switching "embed-resources" from "false" to "true". I don't see where there would be any ambiguity to always treating a setting of the form "/img/about.jpg" as a project directory-relative address, and restricting resource fetches to settings with fully-specified URIs including a scheme such as "http://" or "file://"

Clearly I'm still trying to wrap my head around exactly what "embed-resources" is supposed to accomplish. Is there a fine point here that I'm missing?

[mcanouil]

"Absolute" is to the Quarto project root.

Without a working example or repository, we can't help more.

[blacksqr]

"Absolute" is to the Quarto project root.

Then I guess my response would be, then why doesn't image: /img/about.jpg work as an image file specification in an about: section for a file in the img/ subdirectory of my Quarto project root directory?

But it seems that the answer is, "to accommodate Pandoc".

[blacksqr]

Apologies, I'm still working through this feature conceptually. See #5469 for more details of my confusion.

[mcanouil]

Still hard to understand your issue, but the embed-resources is a Pandoc feature, see https://pandoc.org/MANUAL.html#option--embed-resources.