Accessing meta data with filters

[andrewpbray]

Description

@jimjam-slam and I are working on a custom format and I've run into a few questions about how to process custom meta data. As a running example, say you want to allow authors to specify the following custom options in the document yaml.

---
mykey: val1
---

1. What is the best way to set the default values for custom yaml options?
One option seems to be set mykey = 0, say, at the top of the lua filter. Another option would be to do it in _extension.yml with something like:

contributes:
  format:
    common:
      mykey: 0

So far I've followed option one, but I don't like how squirreled away they are. And approach like option two might make it more transparent. Any other good approaches you could suggest?

2. Is it possible to use namespaces to re-use existing keys?
We're working to add an optional debug mode. My initial attempt was to have it be specified as

---
format:
  myformat-html:
    debug: true
---

and I was puzzled because debug didn't show up as a key available via Meta in a lua filter. My guess is because it's an existing option for debugging Jupyter:

execute:
  debug: true

I can change the name of my key to debug-mode or something and it becomes available in the filter, but I'm curious about the more general question: is there a way to namespace yaml keys?

Thanks!

[cscheid]

These are all very good questions and I'm afraid I don't have sufficiently firm official answers to give!

1. What is the best way to set the default values for custom yaml options?

   One approach you might not have considered is to answer a slightly different question: where do you need these default values? Solve the problem there. So, for example, solve the problem by having a Lua object initializer that fills in the default values when they're missing. That's more or less what we do, except that the default values we get come from a variety of different places (sometimes we need to honor cell defaults, sometimes documents or projects), so we don't really have a uniform software solution. I'd like to do it, but there's more pressing problems in our codebase.

2. Is it possible to use namespaces to re-use existing keys? ... I'm curious about the more general question: is there a way to namespace yaml keys?

   Some keys are disallowed (and our schema should validation warn about them), but we do allow structured YAML values. Is there a top-level key that would be resonant for your custom format? If that key is not used by us, then you can store an arbitrary object under it, and it would work as a reasonable namespace. With that said, I wish we did a better job documenting what parts of our namespace are safe for extensions to consume.

[andrewpbray]

2. Hmm, we could use a top-level key that's the (obscure) name of the format, but that seems a bit incongruous to me. I like the structure in core quarto of format specific options being under, say, format: html:; it makes it clear that they're properties of the format.

I think we'll go with debug-mode for now!