Multiline HTML comments and evaluation of chunks

[boshek]

Description

I see discussions on commenting here and here but I haven't seen anything the outlines this specific issue. Apologies if I have missed it.

Consider this quarto doc called comment-reprex.qmd:

---
format: 
  html: 
    self-contained: true
---

```{r}
head(iris)
```

{{< include child-doc.qmd >}}

and this child doc called child-doc.qmd:

```{r}
head(quakes)
```

Rendering with quarto render produces an html that looks like this:

Great. That works fine. But I am seeing some (what I think to be) strange behaviour with multiline line comments. For example, a multiline comment for the R chunk removes it from the output but the chunk is still evaluated (checked with grep "Sepal" comment-reprex.html):

---
format: 
  html: 
    self-contained: true
---

<!-- 
```{r}
head(iris)
```
 -->

{{< include child-doc.qmd >}}

The same scenario happens when I multiline comment out the include line (checked with grep "stations" comment-reprex.html):

---
format: 
  html: 
    self-contained: true
---


```{r}
head(iris)
```

<!-- 
{{< include child-doc.qmd >}}
 -->

However if one simply does a single line comment the chunks are not evaluated (again checked with grep "stations" comment-reprex.html):

---
format: 
  html: 
    self-contained: true
---


```{r}
head(iris)
```


<!-- {{< include child-doc.qmd >}} -->

Is this a known pattern? I don't see anything mentioned in the commenting section so I am raising this here. If this is an unavoidable issue, for now would you consider a PR to add some text around multiline comments in that section?

Tested on

• macOS
• quarto version 1.5.27

[cscheid]

HTML comments are not supported in Quarto (or Pandoc).

[cscheid]

<!-- {{< include child-doc.qmd >}} -->

Note the Important callout in our documentation:

Important: Include shortcodes need to appear by themselves in a line, and they need to be surrounded by empty lines. This means that you cannot use an include shortcode inside markdown syntax (such as an item in a bulleted list).

[boshek]

Thanks this is helpful. But maybe I missing something with this:

HTML comments are not supported in Quarto (or Pandoc).

Because <!-- {{< include child-doc.qmd >}} --> does work at least from a user facing perspective.

[cderv]

For example, a multiline comment for the R chunk removes it from the output but the chunk is still evaluated (checked with grep "Sepal" comment-reprex.html):

This is an illustration of HTML document are not supported to ignore content. In your case, the knitr engine will still execute and run the chunk because it is seen as a cell and the HTML comment means nothing.

For knitr, there is the specific comment engine : https://yihui.org/en/2022/01/knitr-news/#the-new-engines-comment-verbatim-and-embed that quarto inherits from using knitr

[boshek]

That is a really helpful link thank you. The thing that I am still confused about then is why this works:

<!-- {{< include child-doc.qmd >}} -->

The vscode extension will happily comment out html code which does suggest that comments should work?

[cscheid]

Yuck, I don't think that should be there.