Includes shortcodes resolves paths starting with / differently to YAML header

[cynthiahqy]

Bug description

Paths beginning with / in a document YAML header are resolved as absolute paths, but this appears to be inconsistent with the intended? behaviour as discussed in #9268 (comment). This behaviour is also inconsistent with how "in-text paths" such as for include shortcodes are resolved (i.e. paths starting with / are resolved relative to the project directory).

Steps to reproduce

For the following directory structure:

./
├── _extensions/
│   └── r-wasm/
│       └── live/
│           ├── _gradethis.qmd
│           ├── _knitr.qmd
│           ├── resources/
│           └── templates/
├── _quarto.yml
├── index.qmd
├── modules/
│   ├── starter/
│   │   ├── project-structure/
│   │   │   └── index.qmd
├── partials/
├── references.bib
└── styles/

Let this be the contents of modules/starter/project-structure/index.qmd:

````qmd
---
title: A New Lesson About Quarto
metadata-files: 
  - /modules/_lesson-metadata.yml
include-before-body:
   - file: /_extensions/r-wasm/live/_knitr.qmd
bibliography: /references.bib
---
````

Fails to find the metadata-file:

[1/2] modules/starter/project-structure/index.qmd

processing file: index.qmd           
output file: index.knit.md

Warning messages:
Could not find metadata file /modules/_lessons-metadata.yml

ASIDE: Ideally we'd use a directory level modules/_metadata.yml but that doesn't seem to be inherited by sub-directories (i.e. it skips straight to merging project level metadata).

The relative path workaround technically works but is far from elegant. The includes shortcode resolves relative to the project directory.

````qmd
---
title: A New Lesson About Quarto
metadata-files: 
  - ../../_lesson-metadata.yml
bibliography: ../references.bib
---

{{< include /_extensions/r-wasm/live/_knitr.qmd >}}
````

Expected behavior

YAML header paths and "in-text" paths (e.g. includes, image paths etc.) starting with / resolve the same way (i.e. from the project directory)

Actual behavior

Paths beginning with / in YAML header appear to be treated as absolute paths, while "in-text" they are relative to the project directory.

Your environment

• IDE: VSCode 1.96.2
• OS: MacOS Sonoma 14.6.1

Quarto check output

Quarto 1.6.39
[✓] Checking environment information...
Quarto cache location: /Users/chua0032/Library/Caches/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: /Applications/quarto/bin

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

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

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

[✓] Checking Python 3 installation....OK
Version: 3.10.4
Path: /Users/chua0032/.pyenv/versions/3.10.4/bin/python3
Jupyter: 5.7.2
Kernels: python3

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

[✓] Checking R installation...........OK
Version: 4.3.1
Path: /Library/Frameworks/R.framework/Resources
LibPaths:
- /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources/library
knitr: 1.48
rmarkdown: 2.27

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

[cscheid]

Can you please share a full repository with the directory structure and includes that you're describing? It's hard to track these down without a concrete reproduction to work from.

In any case,

The includes shortcode resolves relative to the project directory.

This is the designed behavior of paths starting in / throughout Quarto. I can't quite follow what else is going on, but {{< include /hello.qmd >}} is supposed to include the file hello.qmd in the same directory as the active _quarto.yml file.

[cderv]

Paths beginning with / in a document YAML header are resolved as absolute paths

I don't think this is true for all YAML fields. As Carlos said, in Quarto path started by / are meant to be relative to project directory.

I don't think we described that very well in our doc and we should fix. There is an example for site-resources at https://quarto.org/docs/websites/website-tools.html#site-resources

I think your report means that we need to check and document all path configuration that we can to check if this is respected.

What you found is a field that does not respect that which is metadata-files

---
title: "Quarto Playground"
format: html 
metadata-files: 
  - /metadata.yaml
---

Content

With a dummy metadata.yml

date: today

gives Could not find metadata file /metadata.yaml

==> quarto preview index.qmd --to html --no-watch-inputs --no-browse

pandoc 
  to: html
  output-file: index.html
  standalone: true
  section-divs: true
  html-math-method: mathjax
  wrap: none
  default-image-extension: png
  metadata-files:
    - /metadata.yaml
  
metadata
  document-css: false
  link-citations: true
  date-format: long
  lang: en
  title: Quarto Playground
  
Could not find metadata file /metadata.yaml
ERROR: Error
    at renderFiles (file:///C:/Users/chris/Documents/DEV_R/quarto-cli/src/command/render/render-files.ts:350:23)
    at eventLoopTick (ext:core/01_core.js:175:7)
    at async renderProject (file:///C:/Users/chris/DOCUME~1/DEV_R/QUARTO~1/src/command/render/project.ts:464:23)
    at async renderForPreview (file:///C:/Users/chris/Documents/DEV_R/quarto-cli/src/command/preview/preview.ts:428:24)
    at async render (file:///C:/Users/chris/Documents/DEV_R/quarto-cli/src/command/preview/preview.ts:172:22)
    at async preview (file:///C:/Users/chris/Documents/DEV_R/quarto-cli/src/command/preview/preview.ts:189:18)
    at async Command.actionHandler (file:///C:/Users/chris/Documents/DEV_R/quarto-cli/src/command/preview/cmd.ts:424:7)
    at async Command.execute (https://deno.land/x/[email protected]/command/command.ts:1948:7)
    at async Command.parseCommand (https://deno.land/x/[email protected]/command/command.ts:1780:14)
    at async quarto (file:///C:/Users/chris/Documents/DEV_R/quarto-cli/src/quarto.ts:190:5)

The includes shortcode resolves relative to the project directory.

This is the designed behavior of paths starting in / throughout Quarto.

So the issue is here that metadata-files don't respect this - and it should probably !

Like this seems to have been fixed for bibliography as discussed in #9268

[cderv]

Like this seems to have been fixed for bibliography as discussed in #9268

So I do get the same type of error with bibliography which is another field passed to Pandoc for processing.

I am not sure those two are yet among the config field that we resolve if they start with / ... 🤔 And possibly we don't apply it on bibliography on purpose (from some code reading I see...)