Controlling document-specific formats and metadata with project profiles

[andrewpbray]

What is the best way to pass formats and metadata to specific documents within a particular project profile?

For example, take a website with three docs, index.qmd, about.qmd, and schedule.qmd. Say that in addition to the vanilla html format, I've created my own custom-html format. My goal is to be able to render two sites from this repo: one with all three files in html format; the second with the first two docs in html format and the third in custom-html format. What I'd like, conceptually, are two project profiles that look like:

# _quarto-vanilla.yml
project:
  type: website

# _quarto-mixed.yml
project:
  type: website
  render:
    - filename: "schedule.qmd"
      format: custom-html

But, as far as I know, specifying the format of individual documents (or additional metadata like date) is not possible at the project level.

The only workaround that occurs to me right now is to do the mixed render as part of two disjoint profiles.

# _quarto-mixed-vanilla.yml
project:
  type: website
  output-dir: _mixed-site
  render:
    - "*.qmd"
    - "!schedule.qmd"

# _quarto-mixed-custom.yml
project:
  type: website
  output-dir: _mixed-site
  render:
    - "schedule.qmd"
    - "!index.qmd"
    - "!index.qmd"
    
format:
  custom-html: default

Then do render and publish with the two profiles.

As the number of documents grows and the metadata gets more document specific, however, the number of profiles needed gets too gnarly for this to be the best solution.

Any ideas?

Thanks!

[andrewpbray]

This didn't get traction the first time, so let me put a point on the key issue here: is it possible to pass metadata to a particular document through a _quarto.yml file?

Something like this:

project:
  render:
    - href: document1.qmd
      date: "10/10/23"
      draft: true    

If these were independent documents, I could put together a script that parses this yaml and does a call to quarto render for each file, with the metadata appended there. When these docs are part of a website with listings, though, this piecemeal approach wouldn't work.

[cscheid]

Could you "invert the dependency"?

For every "multiple-format" file, create a file-content.md file with the content you want, and then
file-plain.qmd and file-custom.qmd, each with a front-matter that points to the right format, output-file: out.html, and {{< include file-content.md >}} as the entire content. file-content.md would itself have no front matter, and just the content you care about.

Then, the plain profile includes all .qmd files without dashes, and *-plain.qmd; analogously for the custom profile

[andrewpbray]

Oh, interesting!

This would work well for certain types of metadata, like draft, but not for date.

My use case: I have a course website that has a full set of course notes in a listing. Two bits of functionality I'm trying to build:

1. At the beginning of a new semester, I want to shift the release dates of all of the documents (notes, assignments) in one central file, say _schedule.yml to conform with the schedule of the new semester.
2. Throughout the semester, I want to render the website on a schedule (using GHA and CRON) so that the lecture notes and assignments are published on their release date. The effect would be to slowly build the website from base bones each semester.

I think your solution would work for 2, toggling from draft: true to draft: false. I don't see how it'd solve 1 though, since each document would have a unique date.

One other approach that I've tried is to run a script before rendering the project that reads through _schedule.yml and writes a small file called meta_temp.md into the same directory as each set of notes containing:

---
date: "10/10/23"
draft: true
---

Then add {{< include meta_temp.md >}} to every note .qmd file. This seems to work, so I can go this route.

---

Misc thoughts

To puzzle through how to implement this, I tried to figure out: where can a document's metadata live? I came up with:

1. In yaml within the document
2. In another .md document that is included
3. In a _metadata.yml file (shared with other docs in the directory)
4. In a _quarto.yml file (shared with other docs in the project of the same format)

3 and 4 are the two settings where metadata is centralized, but it's also shared between docs based on file structure or format. For my particular use case, I needed an option for centralized metadata wasn't shared across docs.