Add option to allow yaml-file keys to overrule their duplicates in the frontmatter/overrule-by-default

[Gewerd-Strauss]

Description

Hello,

this might sound odd, so let's assume a very basic scenario. We have a simple document

---
author: "conssectetur adipiscing elit"
date: now
date-format: "rev. DD.MM.YYYY HH:mm:ss"  
subtitle: "dolor sit amet"
title: "LOREM IPSUM"
---

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

with a default date and date-format.

Now, we convert it with to let's say html while feeding the following yaml file:

citation-location: margin
code-fold: TRUE
date: now
date-format: DD.MM.YYYY
df_print: kable
email-obfuscation: none
fig-cap-location: margin
fig-height: 6.0
fig-title: Figure
fig-width: 8.0
number-depth: 99.0
number-sections: TRUE
reference-location: margin
tbl-cap-location: margin
toc: TRUE
toc-depth: 5.0
toc-location: right
toc-title: Table of Contents

This will result in the following output:

Referring to the documentation on metadata-files, frontmatter keys will overrule those fed via a yaml-file with the argument key metadata-file:

quarto::quarto_render("<manuscriptname>.qmd",pandoc_args = c("--metadata-file","<yamlPath>.yaml"),output_format = "html",output_file = "<filename>.html")

---

To me at least, this doesn't make a lot of sense. Or rather, it is limiting where it doesn't need to be.

From my understanding, quarto will parse the frontmatter keys and then add any non-duplicate keys it will find in the yaml file. However, this brings home the simple disadvantage that you must outsource all keys you might want to change often (or vary between output formats) into the yaml file. So if you need to export to e.g. html, docx and pdf you must specifically define these keys in the yaml file for each and ensure that the frontmatter doesn't contain it.

But what if I need only a single file with a different value for that key? Say I need to hand in a report to three different places for review, and two people want a docx-file with a german-formatted date DD.MM.YYYY, while the third one rather had an html and needs the specific revision date-format: "rev. DD.MM.YYYY HH:mm:ss".
Instead of setting the general assumption to the frontmatter and specifying the deviation when converting to html in its respective yaml-file, I now need call quarto at least twice; and manually edit the file inbetween.

I don't know, that seems unnecessarily complicated to me.

If yaml-file keys would overrule frontmatter ones, this would not be an issue. From my perspective, the negative aspects are almost nonexistent, this would only result in perceived-wrong output if the user uses a random yaml file and doesn't know what keys they are overwriting at-random while doing so. That is an extremely unlikely scenario.

In principle, this would (and imo should) be applicable to all format-agnostic keys.

I hope I could explain my confusion here well enough.

Thank you,
Sincerely,
~Gw

[mcanouil]

Your issue is that you are using the quarto R package which only offers basic support to Quarto CLI.
See quarto-dev/quarto-r#52.

Also, the limitation of --metadata-files is clearly stated in the documentation you mentioned:

Metadata values specified inside the document, or by using -M, overwrite values specified with this option.

This is a direct limitation of Pandoc, see https://pandoc.org/MANUAL.html#reader-options.

If you only need to modify few keys/values, use quarto render --metadata "date-format: whatever".

Alternatively, if you have different setup, you might want to look into project profiles and variables:

• https://quarto.org/docs/projects/profiles.html.
• https://quarto.org/docs/authoring/variables.html.

Another approach, especially if you use knitr and the computing engine is to use parametrised documents and the --execute-param and/or --execute-params options to pass key:value or yaml file with your parameters, see https://quarto.org/docs/computations/parameters.html.

[cderv]

If you only need to modify few keys/values, use quarto render --metadata "date-format: whatever".

@mcanouil I believe this does not work for date-format. Same issue as in #6013 where @dragonstyle commented

There are quite a few metadata values that bypass the isQuartoMetadata check (including citation) - I think it would be a larger thing to try to dig into all of them and ensure that they are processed appropriately and is likely to cause regressions...

date-format is among them.

@dragonstyle I think we could benefit an issue to track this, as behavior will depend which option is support for override in -M flag. I'll open one.

For now, doing

quarto render report/test.qmd -M date-format:"rev. DD.MM.YYYY HH:mm:ss"

won't allow to override the default date-format set in the YAML header.

So it is right that there is no easy way to override a YAML config set in frontmatter of a document, using quarto_render R function or quarto CLI directly.

[mcanouil]

Indeed, some options are required by Quarto processing to set the actual metadata sent to Pandoc, thus they have to be set earlier.

[cderv]

Indeed, some options are required by Quarto processing to set the actual metadata sent to Pandoc, thus they have to be set earlier.

See #6123 - Some are working but other are not. Inconsistent behavior

[mcanouil]

Maybe in the schema a tag of some kind to state if can be overwritten or not (or passed to Pandoc as is) could help for references pages.

[cderv]

Maybe in the schema a tag of some kind to state if can be overwritten or not (or passed to Pandoc as is) could help for references pages.

yes if we consider that this is a feature to not being able to override a metadata. For now, I consider this myself a bug. Any metadata should be able to be override using --metadata flag at Command Line.