HTML comment above metadata breaks date alias

[ropeladder]

Bug description

If I have the following as metadata, it interprets date: today as today's date and renders it into the final document, as per the docs:

---
title: "test"
format: pdf
date: today
---

## Quarto
...

If I add an HTML comment above the metadata, it no longer parses date: today into a date, and just writes "today" in the document instead:

<!-- test -->
---
title: "test"
format: pdf
date: now
---

Steps to reproduce

No response

Actual behavior

No response

Expected behavior

No response

Your environment

• very old version of Ubuntu

Quarto check output

quarto check

Quarto 1.5.57
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.2.0: OK
      Dart Sass version 1.70.0: OK
      Deno version 1.41.0: OK
      Typst version 0.11.0: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.5.57
      Path: [...]/quarto-1.5.57/bin

[✓] Checking tools....................OK
      TinyTeX: (not installed)
      Chromium: (not installed)

[✓] Checking LaTeX....................OK
      Using: Installation From Path
      Path: [..]
      Version: 2018

[mcanouil]

That's not a bug.

As documented, Quarto expects the YAML block to be the first thing in the document.

Note that HTML comments is only valid in the context of HTML.
It's not a general comment syntax.

Side note: the current stable release is 1.6.42.

[ropeladder]

When using HTML comment above the YAML header it does seem to run fine otherwise. But it makes sense that that wouldn't be something you'd want to support. Thanks!

[mcanouil]

It's because Pandoc merges metadata blocks and it can handle multiple blocks, but the date comes from Quarto not Pandoc and is not a "static" metadata.

I'm reopening to let the maintainers decide if there is something to be done here.

[cderv]

Thanks for the report. To be complete here is what I see (using HTML to avoid latex rendering)

<!-- test -->
---
title: "test"
format: html
date: today
---

## Quarto
...

This does work in the sense that the date is correctly retrieved, but something is off as the YAML field is not removed and shown as it in the document (despite it being used)

Adding a line space shows the behavior you described

<!-- test -->

---
title: "test"
format: html
date: today
---

## Quarto
...

The date is not replaced

And this is due to what @mcanouil explained: We are handling date only when in top YAML header
Our doc does not say it explicitly (https://quarto.org/docs/reference/dates.html) though, the YAML configurations are supposed to be on top with Quarto.

I don't know if our linter should detect this maybe 🤔 It could be hard as a YAML block at the top is not mandatory, and YAML block can be spread inside the document as Pandoc's supports its.

We just don't resolve some Quarto specific configuration unless in top block;

By the way, if you want to comment, you can comment in YAML or just below the block.

@cscheid do you think there is some ideas to dig as you are working on a new Markdown reader. Should all YAML block be caught and handled as PandocMetadata in our Quarto processing ? I think we only consider the top one right now.

[cscheid]

(Yes, this is a Quarto bug.)