Move "markdown envelope" earlier in Quarto toolchain

[mcanouil]

Quarto has a mechanism for rendering snippets text into markdown through the entire filter chain (so that eg. crossrefs are resolved properly). Internally, we call it the "markdown envelope". It interacts badly with some of the ordering in Quarto's rendering process, so we need to fix it.

Original comment

Even in block position, it's still rendering as {{< include _footer.qmd >}} instead of © 2025 My Website..

Ok, that makes sense and yes, it is a block! So let me give a full explanation:

As a very short answer, it's a shortcoming of Quarto that the include shortcode doesn't work on markdown values in _quarto.yml the same way that {{< version >}} does.

Notice that I'm not calling it a bug. That's because it's a design shortcoming. The shortcoming comes when when these two following facts interact:

• include needs to make document inclusions available at the time of engine execution, and so include needs to do its thing very
• Markdown content in YAML is almost entirely handled by Pandoc (for example for title fields, etc). However, we do have the concept of a Markdown envelope, which is built by Quarto ahead of Pandoc (such as websites), but that handling happens relatively late in our pipeline. Crucially, that's after engine execution, and hence after include has already been resolved.

One solution is to move Quarto's handling of Markdown-in-YAML ahead of include execution.

This is a relatively large change in Quarto: it affects engine detection. It changes what Markdown is available during the resolution of include shortcodes. If we were to make such a change, engine detection now would see the markdown envelope.

I actually like this; we need to make the Markdown envelope more explicit and document it. But it needs to be done carefully.

Originally posted by @cscheid in #13001 (reply in thread)