Docs enhancement: options for listing templates and metadata listings

Discussed in https://github.com/quarto-dev/quarto-cli/discussions/4358

^{Originally posted by jimjam-slam February 14, 2023}
I've been playing around with listing templates and metadata listings. The options described in the docs are:

1. providing a glob of documents to a listing,
2. providing inline yaml content,
3. providing an external yaml file

There're a couple of things I think it's worth highlighting:

If you provide inline yaml contents in a post's listing, you can iterate over it as items for that listing's template. For example, I can provide a list of wines featured in a post under contents as a string array and then iterate over them with:

<% for (const wine of items) { %>

But it's not obvious from the existing docs that if I then want to list the wines featured in a series of posts, I can also write another template for my index page, give it contents: *.qmd, then iterate over the wines in each post through its listing.contents:

<% for (const doc of items) { %>
  <a href="<%= doc.path %>"><h2><%= doc.title %></h2></a>
  <ul>
    <% for (const wine of doc.listing.contents) { %>
    <li><%= wine %></li>
    <% } %>
  </ul>
<% } %>

The only reason I mention this is that nested custom metadata is a pretty common use case, and the existing docs present options for surfacing that metadata either in that doc's template or in another doc's template—but not both.

The other thing not explicitly mentioned is that you can also provide a glob string of yaml files, in which case it seems like they're all concatenated into one big array. I don't think this is quite as flexible for a lot of blogging use cases, because you lose the document context here, but it does mean you don't have to worry about going through listing.contents—it's the same syntax regardless of where you're accessing the data from.

Anyway, just wanted to highlight these features since they really do allow Quarto to go toe-to-toe with other static site generators (for the relatively few people who might want to pop the hood a bit more)!

Full gist demo of this functionality here!