Includes shortcodes resolves paths starting with `/` differently to YAML header

Open
#11,839 4 comments 0 reactions 1 assignee View on GitHub

@cderv is already working on this.

Since Jan 10, 2025.

Assessment

This issue has not been assessed yet.

Description

bug includes
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 https://github.com/quarto-dev/quarto-cli/issues/9268#issuecomment-2036965158. 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

Dominant language
JavaScript
Stars
6k
Forks
458
Avg merge
1d 9h
Merged PRs (30d)
41

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from quarto-dev/quarto-cli

All issues in quarto-dev/quarto-cli

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.