include 'header' section in yaml

[fmichonneau]

I am writing a document that needs to be rendered as GitHub flavored markdown and needs to include the key header in the YAML front matter which in an array that includes a path to a file. Something like:

---
title: "A title"
header:
  image: "/somewhere/beautiful.jpg"
---

rest of the document

if I try to include the header key in my source qmd file as:

---
title: "A title"
header:
  image: "/somewhere/beautiful.jpg"
keep-yaml: true
format: gfm

---

rest of the document

Then quarto errors because I assume that for quarto (or pandoc) header has a special meaning and expects the value to be formatted a specific way:

ERROR: Validation of YAML front matter failed.
ERROR: In file test.qmd
(line 4, columns 3--36) Key header has value image: "/somewhere/beautiful.jpg", which must be a string
3: header:
4:   image: "/somewhere/beautiful.jpg"
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5: format: gfm
✖ The value image: "/somewhere/beautiful.jpg" is object.
ℹ The error happened in location header.

ERROR: Render failed due to invalid YAML.

Is there a way to add this header key without having quarto fail?

Thanks!

[cscheid]

As a workaround, you can add validate-yaml: false to disable validation entirely. Can you point me to the github documentation that talks about this YAML key? I want to make sure we get the schema right.

[fmichonneau]

Thank you for this!

In my case, it's for a Jekyll-based blog using the minimal mistakes theme.

The header: key is used for several things including:

• https://mmistakes.github.io/minimal-mistakes/layout/uncategorized/layout-header-overlay-image/
• https://mmistakes.github.io/minimal-mistakes/layout/uncategorized/layout-header-video/

[cscheid]

Thank you.

In general, we are not planning on supporting arbitrary third-party packages that have their own expectations of yaml metadata. The validation workaround will do the job for you, but it won't work in general (there could be actually conflicting YAML keys). I would consider using quarto's own support for themes, if that's a possibility for you.