How to write the YAML file that feeds listings?

[ramiromagno]

Description

Hi,

Thanks for the amazing software you make.

I'm struggling with metadata file listings.

How to write the YAML file that feeds the listing? What are the "special" reserved fields? For example, I could verify that some fields are treated specially, like description, date, seemingly image is too, although I have not managed to indicate a path that renders the image in the website.

So, is there a list of fields that are default and what special treatment they get?

Here is a bit of context:

• index.qmd: quarto index file
• oss.yml: YAML with metadata to feed the listing
• logo.svg: An image in the same folder as index.qmd and oss.yml.

index.qmd:

---
title: "Open Source Software"
listing: 
  - id: oss
    contents: "oss.yml"
    type: grid
    sort:
      - "date"
---

oss.yml:

- name: entry_A
  description: "some description"
  Authors: "Some authors"
  href: https://quarto.org
  date: "2025-03-20"
  image: "logo.svg"

This is what I see:

I did read:

• https://quarto.org/docs/websites/website-listings.html#yaml-listing-content
• https://quarto.org/docs/websites/website-listings-custom.html#metadata-file-listings

[mcanouil]

Take a second reading at https://quarto.org/docs/websites/website-listings.html#yaml-listing-content

There are no href, name, or Authors.
If you want to use such fields, then you have a create a custom listing that uses them.
To be clear, the fields used by the default listings are the ones described on the same page: https://quarto.org/docs/websites/website-listings.html#listing-fields
Only path is not listed before the YAML section where an example shows it.

[ramiromagno]

There is no mention about what the default fields are. I appreciate the reply on the negative, i.e. that those fields are not default but my question was about the default ones. Are you implying that those fields below, indicated by way of example in the docs, are the default ones?

- title: "Archived Item 1"
  author: Norah Jones
  date: 2020-01-01
  path: "archived/archived-item-.html"
  categories: [archived, technology]

If that is the case then it's not exhaustive because I noticed that image and description are also special and are not listed in that example.

So, my question remains: which fields are default?

[ramiromagno]

Okay, your update on the post helped.

Is it possible to use the image field from the YAML? How should the path be indicated? Because my attempts with paths relative to the whole website, relative to the index file, etc.. all failed.

[mcanouil]

Okay, your update on the post helped.

Is it possible to use the image field from the YAML? How should the path be indicated? Because my attempts with paths relative to the whole website, relative to the index file, etc.. all failed.

What do you mean? What did you try exactly?

[ramiromagno]

I have shared the yaml above.

…

On Thu, 20 Mar 2025, 19:45 Mickaël Canouil, ***@***.***> wrote: Okay, your update on the post helped. Is it possible to use the image field from the YAML? How should the path be indicated? Because my attempts with paths relative to the whole website, relative to the index file, etc.. all failed. What do you mean? What did you try exactly? — Reply to this email directly, view it on GitHub <#12330 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AEXRG4EKSLLFLNPR56IQ6GL2VMLGHAVCNFSM6AAAAABZODAXUWVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTENJWHA3TMOI> . You are receiving this because you authored the thread.Message ID: ***@***.*** com>

[mcanouil]

You said you've tried various things for the paths. That's only one.

Note that your example is not reproducible.

Could you provide a Git repository showing what you've tried?

edit: I can't reproduce your issue either using path absolute to the project root or with relative paths image: thumbnail.jpg

[ramiromagno]

In your example you're using the image field in the index file (index.qmd) not in the yaml. My question is about indicating an image for an item that is provided in a YAML file. I will try to create a github repo with a reprex.

[mcanouil]

Again, please provide a concrete example.
It does not matter if the YAML content comes from within or an external file.

[mcanouil]

@ramiromagno I spent time creating an example to demonstrate that it does work (directly based on quarto create project blog). Rather than debating or suggesting that my example is incorrect, I kindly urge you to concentrate on providing the necessary details for us to reproduce your issue.
I apologise for being direct, but the answers to your initial questions were already available in the documentation you mentioned you had read. Please be considerate of the time and effort required to assist you, as resources are not unlimited.

[ramiromagno]

Mickaël, you're absolutely right, my apologies.

Thanks for all your time and trouble, I can reproduce your example. I will look into my specific case more carefully.