How are metadata paths resolved?

[andrewpbray]

Description

Minimal repo: https://github.com/qmd-lab/quarto-class-website

I've run into some unexpected behavior in how paths are resolved when passed as metadata in separate yml files for a website. I see this in two different settings:

I. Including contents in a document listing through contents.yml file.
II. Including extra sidebar contents in _quarto.yml by linking to sidebar-nav.yml through the metadata-files key.

If sidebar-nav.yml is in the same directory as _quarto.yml and if contents.yml is in the same directory as the qmd with the listing, there are no problems. If they're in different directories, however, things go awry.

I. Listing Contents

For example (and in the minimal repo)slides.qmd has a listing like this:

---
listing:
  - id: slides-listing
    contents: 
      - assets/quarto-class-website_files/slides-contents.yml
      # - slides-contents.yml
    sort: "date desc"
    type: grid
    fields: 
      - title
      - subtitle
      - image
    categories: false
toc: false
---

# Slides

:::{#slides-listing}
:::

where slides-contents.yml is just this:

- path: 1-probability/1-random-variables/slides.qmd
- path: 1-probability/2-binomial/slides.qmd
- path: 1-probability/3-conditional-probability/slides.qmd

The wrinkle is that slides.qmd renders like this:

Those thin cards are actually good clickable links, but it clearly failed to pull the metadata as the warning says:

WARNING: File /Users/andrewbray/Dropbox/Research/quarto-extensions/quarto-class-website/assets/quarto-class-website_files/1-probability/1-random-variables/slides.qmd in the listing 'slides-listing' contains no metadata.

If I change the paths to look like /1-probability/1-random-variables/slides.qmd, the warning changes to :

WARNING: File /1-probability/1-random-variables/slides.qmd in the listing 'slides-listing' contains no metadata.

If I change the path to ../../1-probability/1-random-variables/slides.qmd, the document listing looks fine but the links no longer work, with the warning:

WARNING: Unable to resolve link target: ../../1-probability/1-random-variables/slides.qmd

Any idea what's going on here? It seems that the path resolution for the links is different than the path resolution for the metadata in a case where the .yml contents file is in a different directory than the listings qmd.

II. Extra Sidebar Nav Contents

My _quarto.yml looks like this:

project:
  type: website

website:
  sidebar:
    contents:
      - href: index.qmd
        text: Home
      - href: slides.qmd
        text: Slides
      - href: problem-sets.qmd
        text: Problem Sets
    
metadata-files:
  - assets/quarto-course-website_files/sidebar-nav.yml
#  - sidebar-nav.yml

And sidebar-nav.yml looks like this:

website:
  sidebar:
    contents:
      - 1-probability/1-random-variables/notes.qmd
      - 1-probability/2-binomial/notes.qmd
      - 1-probability/3-conditional-probability/notes.qmd

When the website renders, however, the sidebar only contains Home, Slides, and Problem Sets. Prepending the contents paths with either / or ../../ doesn't appear to do anything and I get no warnings. It is fixed, though, by moving sidebar-nav.yml into the same directory as _quarto.yml.

As far I can tell, this is not related to

• Why is my listing not showing up?.

Thanks for your help.

[dragonstyle]

Howdy!

I. Slide Listing

For part I, using our latest builds (which should be pretty the shipping 1.4 release, though I'm a little ahead of that) - I cloned your repo and just ran it and things seemed ok to me):

I took a quick peak through the changes in 1.4 and don't necessarily see one that I think will fix this, but there are bunch of improvements to listing handling so wouldn't be totally shocked if we changed something.

II. Sidebar Contents

I'm tinkering with this now - I'll post here when I know more.

Note that there is possibly useful work happening over here for 1.5 with regards to system behavior for draft documents (doing a better job of excluding draft documents from websites and also likely making it easier to denote what documents are draft):
#8509.

I think I should have something ready pretty shortly that might make life a little easier.

[dragonstyle]

II. Sidebar Contents

I was able to have this work without much issue (both in the root folder and in subfolder). The biggest thing that I needed to do was to be sure that the paths were relative to the _quarto.yml file, no matter where the metadata-file is being stored. We merge these files into the project yml file, but don't do path resolution prior to merging, so any paths will pass directly into the _quarto.yml file as is. This makes it tempting to keep them in the same directory as the _quarto.yml file just so that the paths are less confusing...

LMK if these answers clear things up, if not I can keep digging...

[andrewpbray]

Thanks for taking a look!

II. Sidebar Contents

Hmm... it looks to me like the current state of that repo conforms to the path structure you suggest. _quarto.yml has metadata-files: [assets/quarto-course-website_files/sidebar-nav.yml] and that file has paths of the form 1-probability/1-random-variables/notes.qmd which are relative to the project directory. That was the structure that I expected, but I'm still getting missing entries in the sidebar (both on v 1.3.433 and v 1.4.549).

Here are those missing entires (sidebar-nav.yml):

website:
  sidebar:
    contents:
      - 1-probability/1-random-variables/notes.qmd
      - 1-probability/2-binomial/notes.qmd
      - 1-probability/3-conditional-probability/notes.qmd

Ah, I think I might know our disconnect: the link to the repo above is to a particular commit. I did this so I could continue troubleshooting, but I realize I probably should have put my subsequent work on a different branch - apologies!

git checkout 4aa7a0bfdcc242b2d727822e6e13745e22b13694 should get us looking at the same repo. That particular commit exhibits the subdir structure that causes the issue; in current commit I moved all files into the project directory so that I could continue working on other components of that repo.

[dragonstyle]

Ok getting to that commit was definitely helpful - I could reproduce it right away!

I think the issue is actually a simple typo (the metadata-files is pointing to an invalid path, but we don't error ?! ):

# Original
metadata-files:
  - assets/quarto-course-website_files/sidebar-nav.yml

# Should be:
metadata-files:
  - assets/quarto-class-website_files/sidebar-nav.yml

I'll see if we can throw in this case - I don't think its desirable to silently ignore failures of this sort (for just this reason!)

[dragonstyle]

(Fixed here a868d8e)