Why is front matter expected to end with hypens (---) in Jupyter notebooks?

[th0ger]

Description

Thoughout Quarto documentation, front matter is both started and ended with hyphens

---
[FRONT_MATTER
---

Especially this is noted in Jupyter front matter. I'm primarily concerned with jupyter here.

However, YAML 1.2.2 states that:

YAML uses three dashes (“---”) to separate directives from document content. This also serves to signal the start of a document if no directives are present. Three dots ( “...”) indicate the end of a document without starting a new one, for use in communication channels.

So, essentially Quarto expects us to include two YAML documents (the second being empty) in the first raw cell...

Does Quarto allow the following front matter syntax, which is all valid single-document YAML:

1. ---
[FRONT_MATTER]
...
2. [FRONT_MATTER]
...
3. [FRONT_MATTER]

My use case: I am doing a parser to modify single front matter attributes, using Python (nbformat + ruamel.yaml). Round-trip parsing of the YAML with ruamel yields and additional --- [FRONT_MATTER] --- null ... which is essentially correct.

[cscheid]

There's a difference between "YAML directives" as defined by the YAML standard and YAML front-matter as defined by Pandoc. In YAML standard parlance, "document content" is actually just YAML.

Does Quarto allow the following front matter syntax, which is all valid single-document YAML:

1. ---
[FRONT_MATTER]
...
2. [FRONT_MATTER]
...
3. [FRONT_MATTER]

My use case: I am doing a parser to modify single front matter attributes, using Python (nbformat + ruamel.yaml). Round-trip parsing of the YAML with ruamel yields and additional --- [FRONT_MATTER] --- null ... which is essentially correct.

Quarto (through Pandoc) expects YAML metadata blocks to use Pandoc's metadata syntax: https://pandoc.org/MANUAL.html#metadata-blocks

Quoting the document,

A YAML metadata block is a valid YAML object, delimited by a line of three hyphens (---) at the top and a line of three hyphens (---) or three dots (...) at the bottom. The initial line --- must not be followed by a blank line. A YAML metadata block may occur anywhere in the document, but if it is not at the beginning, it must be preceded by a blank line.

But I'm not sure what you're asking. Is something not working in quarto itself?

[th0ger]

Hi @cscheid

I'm asking if Quarto is supposed to allow ending the frontmatter with ....
(Because it makes it possible for me to modify the frontmatter with standard yaml libraries.)

Your answer above is "Yes", because Pandoc allows this. Great :-)

Unfortunately Quarto throws an error. Should I file a bug report?

Expected front matter to end with '---'

Error: Expected front matter to end with '---'
    at validateDocumentFromSource (file:///opt/quarto/bin/quarto.js:84346:19)
    at async renderFiles (file:///opt/quarto/bin/quarto.js:86587:55)
    at async render (file:///opt/quarto/bin/quarto.js:90681:21)
    at async renderForPreview (file:///opt/quarto/bin/quarto.js:102415:26)
    at async render (file:///opt/quarto/bin/quarto.js:102310:20)
    at async Object.promise (file:///opt/quarto/bin/quarto.js:102466:33)

[cscheid]

Yes, that's a bug we should fix.

I'll note that we currently have our plates full, and since this seems like an easy workaround ("don't use ..."), it's not exactly high priority. But yes, this is a bug we should fix.

[cderv]

I opened

• Quarto front matter expects ending with --- while pandoc allows ... #6698

to track this for future us when we have time

[th0ger]

Thanks. I'll make a hack in my project and leave a note to future self 😆