[FR] Support Github callouts in HTML preview for github_document()

[etiennebacher]

Hello, Github introduced the callout syntax about 1.5 years ago. I would like to use these callouts in the README of some packages, but they are currently not well rendered on the pkgdown website. It looks like this is due to R Markdown. Currently the output is this:

---
output: github_document
---

> [!NOTE]
> Highlights information that users should take into account, even when skimming.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.

while I would expect this:

Is this something that R Markdown could support?

---

Reprex of this issue with pkgdown: https://github.com/etiennebacher/pkgdown.callout

[cderv]

First let's talk about the .md output which is what `github_document targets. Screenshot you shared are about a HTML rendered output. I believe the .md you get is the same as when I tried

> \[!NOTE\] Highlights information that users should take into account,
> even when skimming.

> \[!IMPORTANT\] Crucial information necessary for users to succeed.

> \[!WARNING\] Critical content demanding immediate user attention due
> to potential risks.

So square brackets are escaped, which you obviously don't want.

The callout syntax is a GFM only syntax but .Rmd documents are parsed by Pandoc as Pandoc's markdown. So if you are using a syntax that is a raw syntax for the output your are targetting, you need to leverage raw block from Pandoc's Markdown
See https://bookdown.org/yihui/rmarkdown-cookbook/raw-content.html

You would do this in HTML if you want to include HTML code, or for PDF output if you want to insert raw latex. That works the same for GFM output

Try

---
output: github_document
---

```{=gfm}
> [!NOTE]
> Highlights information that users should take into account, even when skimming.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.
```

This will produce the expected .md output, rendered correctly on Github.

the HTML preview you get from rmarkdown would still be not the same as on github. But this is because we have no access to Github's own HTML renderer. So we do our best, and this callout rendering will be tricky to do !

they are currently not well rendered on the pkgdown website

My last comment probably apply to pkgdown rendering. I believe pkgdown expect you to build the README.md from your Rmd version with github_document(). And then they are responsible to convert this README.md to a HTML version for the index page. I don't think they use github_document() but rather their own pandoc format conversion. Not sure they know how to handle the Callout syntax too, so I don't think it would be rendered as you expect anyway.

Doing it would be like providing support for our HTML preview of github_document, and would probably a Lua filter to convert the unknown GFM syntax if possible to a HTML version and add the required CSS to format it.

Framework which have a Callout syntax in Markdown like Quarto has could provide a syntax that would output nicely formatted for GFM and for HTML outputs. In pre-release quarto 1.4, GFM callout are supported output for Quarto callouts

• Callout rendering in gfm quarto-dev/quarto-cli#6935

Hope it helps understand ! Keep me updated once you try the new syntax for your pkgdown website

---

About what I said above:

the HTML preview you get from rmarkdown would still be not the same as on github. But this is because we have no access to Github's own HTML renderer. So we do our best, and this callout rendering will be tricky to do !

I'll transform this FR to a HTML preview request for this new callout syntax.

[etiennebacher]

Thanks for the detailed explanation, @cderv, it's very clear. Using your code snippet above indeed generates the correct syntax for the callout in the md file and is well rendered on Github.

As for pkgdown, I don't have the motivation to make a Lua filter and the CSS styling for these callouts, but do you think it should be a FR there?

[cderv]

As for pkgdown, I don't have the motivation to make a Lua filter and the CSS styling for these callouts, but do you think it should be a FR there?

Yes I think so. I believe if GFM callouts are used in a README.md, it won't render well on pkgdown website. Though in that case, I guess another index page should be used probably.

Anyhow, feel free to open one there... or wait for someone else who needs it :) GFM callouts are quite new I believe.