Document "reserved" YAML parameters

[christopherkenny]

What would you like to do?

Report an issue on quarto.org

Description

There have always been YAML parameters that can't be used aside from their official purpose, such as authors, as these get processed by Quarto. This is discussed implicitly in the explanation of the normalization of author schema here.

With the introduction of brand.yml processing, this has extended to include some larger set of parameters that can't be used by template authors. For example, in custom formats for Typst, you can no longer use logo as a parameter without special care, as it gets eaten up by the brand processing.¹ Ideally, when brand.yml isn't used, this behavior wouldn't occur, but that seems a bit complicated and harder to work with.

As such, I think it would be very helpful to create a short page under the creating extensions pages which documents which parameters are, in a sense, now reserved and can't be used for custom templates. Perhaps also keeping track of when they become "reserved" and by what feature.

Footnotes

1. In the case of logo, if you were previously using it as a path, then you can recover from the normalization by substituting $logo.path$, but this is not immediately clear, nor documented anywhere I could find. ↩

[cscheid]

Thanks! Yes, that's big on the list of things we will be doing in the near-to-medium term.

(You'll soon start to see a large-ish number of under-the-hood changes in Quarto that will allow us to do more than just document these parameters. But you are completely correct that the general situation needs to be improved.)

[mcanouil]

In a related note: if the extensions' parameters are scoped, you are less likely to need to know for all Quarto/Pandoc reserved YAML.

• Scope the extensions configuration such as extensions.<name>.<option> #12894

(This does not really solve the use of top-level YAML variables)

[christopherkenny]

Thank you both, I appreciate the responses.