_metadata.yml overwrites format configuration in document yaml, inconsistent with Quarto documentation

[ar-puuk]

Description

Initially posted in #7101.

Hi, jumping in on this issue as I'm encountering (what I think is) the same issue with my Quarto website related to how document-level format options interact with _metadata.yaml.

I have a _metadata.yaml file in my posts folder that sets common format options for html, typst, and docx. This works well for blog posts, as they all share the same formatting.

However, I occasionally want to include a revealjs presentation alongside my posts. When I try to specify format: revealjs in the front matter of the presentation document, it appears to be overridden by the _metadata.yaml settings, which don't include revealjs. As a result, Quarto attempts to render the presentation as an html document and fails with the following error:

quarto render

ERROR: NotFound: The system cannot find the file specified. (os error 2): rename 'D:\GitHub\quarto-format-override-issue\posts\presentation.html' -> 'D:\GitHub\quarto-format-override-issue\docs\posts\presentation.html'

Stack trace:
    at Object.renameSync (ext:deno_fs/30_fs.js:267:3)
    at safeMoveSync (file:///C:/Program Files/Quarto/bin/quarto.js:2354:14)
    at renderProject (file:///C:/Program Files/Quarto/bin/quarto.js:87372:17)
    at eventLoopTick (ext:core/01_core.js:175:7)
    at async Command.actionHandler (file:///C:/Program Files/Quarto/bin/quarto.js:91975:32)
    at async Command.execute (file:///C:/Program Files/Quarto/bin/quarto.js:8253:13)
    at async Command.parseCommand (file:///C:/Program Files/Quarto/bin/quarto.js:8143:20)
    at async quarto (file:///C:/Program Files/Quarto/bin/quarto.js:133948:9)
    at async file:///C:/Program Files/Quarto/bin/quarto.js:133978:9
    at async file:///C:/Program Files/Quarto/bin/quarto.js:133830:20

This seems to happen because _metadata.yaml specifies a set of formats that ends up excluding revealjs, even if it's defined at the document level.

I believe it would be helpful if Quarto allowed document-level format declarations to override folder-level _metadata.yaml settings (in line with what is mentioned in the Quarto documentation) or at least provided a flag like format-override: true or format-override: merge.

This would prevent the need to duplicate format settings across dozens of documents. For example, I currently have a shared _metadata.yaml like this:

format:
  html:
    toc: true
    number-sections: true
    number-depth: 2
    html-math-method: katex
    code-link: true
    code-tools: true
  typst:
    toc: true
    number-sections: true
    number-depth: 2
  docx:
    toc: true
    number-sections: true
    number-depth: 2

But if I add a single Revealjs presentation, I’d need to move this format block into each individual post just to make one exception.

@mcanouil the minimum reproducible example is: https://github.com/ar-puuk/quarto-format-override-issue

Thanks for the great tool and your time looking into this!

Quarto Verion: 1.7.32
Windows Version: Windows 11 x64

Happens in both RStudio and Positron
R Studio Version: 2025.05.1 Build 513
Positron Version: 2025.08.0 (System Setup) Build 63

[mcanouil]

See:

• format keyword in document not overriding _metadata.yml #9605
• [docs] Format in _metadata.yml are merged with in-document and used in priority over project config #8968