Using multiple include statements with individual front matter - not sure if this is a bug

[warrenallen]

I am trying to use multiple include statements in one page. I have one .qmd for each document that I want included and each one has its own front matter. Example:

The "outer" document

{{< include section1 >}}
{{< include section2 >}}
{{< include section3 >}}

Example of each section document

---
title: "Section 1"
description: "Lores gypsum dolor sit met it sumo facet re constitute."
---

(body of the section)

Expected result

One page that displays each section one after the other.

Observed result

I get one page, sections 1 through 3, however:

1. The front matter for the final .qmd appears where the front matter for the first .qmd would be.
2. No other front matter fields are rendered.

It appears that the "outer" document reads the front matter for the first of the included documents and then ignores the front matter from the rest of the included documents. Is there anything I'm missing? Or a workaround I can't see? Or a bug?

[mcanouil]

why included documents have titles? What do you expect to happen when the main document ends with 4 titles?
Sections/chapters/etc. are defined with # or any markdown syntax giving headers.

To avoid this weird use case in the future, maybe the include shortcut should strip out the metadata 🤔.

[warrenallen]

Thanks. This makes sense, and I was definitely working with an erroneous mental model of how this works.

[mcanouil]

Depending on what you want, it's possible to include the content without the yaml part.
For example, you can take a look at #2202 (comment) where I did the opposite, i.e., I only included the yaml part to use it as the current document yaml.

[cscheid]

include statements are quite literal: think of them as copy-pasting the entire destination file into where you declared the short code. Front-matter in included files are almost always going to create unintended behavior: they are not scoped to the included document (and likely will never be, this is behavior we ultimately inherit from pandoc and will not deviate from).

[warrenallen]

This makes sense now. Thanks. Looks like I need to dig into the guide on how to use projects in order to do what I was hoping to do.