Set the option unsafe = true for the Markdown renderer goldmark

maelle commented 4 years ago

Currently the shortcode() function's default type is Markdown but if I follow things correctly when rendering from .RMarkdown to .Markdown once will loose the shortcode:

Shortcodes with "%" delimiters are rendered before being passed to Goldmark. https://gohugo.io/content-management/shortcodes/#shortcodes-with-markdown (Hugo > v0.55)
By default Goldmark omits all html content. https://gohugo.io/getting-started/configuration-markup/#goldmark (Hugo > v0.60)

I might be missing something, and .RMarkdown are probably not the most used file type. Maybe a note in the docs makes sense, maybe it's not blogdown's role at all.

By filing an issue to this repo, I promise that

[x] I have fully read the issue guide at https://yihui.org/issue/.
[x] I have provided the necessary information about my issue.
- If I'm asking a question, I have already asked it on Stack Overflow or RStudio Community, waited for at least 24 hours, and included a link to my question there.
- If I'm filing a bug report, I have included a minimal, self-contained, and reproducible example, and have also included xfun::session_info('blogdown'). I have upgraded all my packages to their latest versions (e.g., R, RStudio, and R packages), and also tried the development version: remotes::install_github('rstudio/blogdown').
- If I have posted the same issue elsewhere, I have also mentioned it in this issue.
[x] I have learned the Github Markdown syntax, and formatted my issue correctly.

yihui commented 4 years ago

@maelle Personally I really dislike the default unsafe: false of Goldmark. This default is extremely confusing, and I think they were overly cautious about the potential security issues. I think it is worth noting this surprising behavior of Goldmark on the help page of shortcode(). Thanks a lot for your suggestion!

To those who came to this issue from a message emitted by blogdown in the R console

If your config file is config.yaml, you may add the following setting to your config.yaml:
```
markup:
  goldmark:
    renderer:
      unsafe: true
```

If your config file is config.toml, add the following setting instead:

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true

That's all you need. You can skip the rest of replies below.

Why setting `unsafe` to `true`?

Scary as the option unsafe = true sounds, it doesn't necessarily make your site "unsafe." Without this setting, your Hugo's shortcodes are likely to fail to render (if you have any in your posts), and any raw HTML content in posts will be ignored, i.e., you can't mix raw HTML content into your Markdown content. The consequence is that all elements created with HTML code will disappear on your pages and no HTML tags will function, e.g., <style>, <script>, <img>, and <div> are all going to fail.

This only applies to the Markdown renderer goldmark, which is the default renderer of Hugo since v0.60.0. Unfortunately, Hugo's core developer refused to change unsafe to true by default (https://github.com/gohugoio/hugo/issues/6581), although no other Markdown renderer to my knowledge disallows HTML in Markdown by default.

maelle commented 4 years ago

For the record I switched to unsafe true too 😁

maelle commented 4 years ago

Just to clarify, are you expecting a PR for this?

yihui commented 4 years ago

I just added it to the help page by myself. Thank you!

yihui commented 3 years ago

FYI with the current development version, users will see a reminder message that tells them to set unsafe to true, if this option has not been set and the markdown renderer is goldmark. It should be much less likely that users get bitten by (lack of) this option silently from now on.

setgree commented 3 years ago

Hello,

Hope all is well and you're having a nice Thanksgiving. I came to this page because of the following warning, when I started my blogdown .Rproj:

--------------------------------------------------------------------------------
'You are recommended to set the option 'unsafe' to true for goldmark in config.toml. See https://github.com/rstudio/blogdown/issues/447 for more information.
--------------------------------------------------------------------------------

And I just want to voice that I have no clue what the issue is talking about...I did it because you suggested it and I trust your judgement on these matters but would it be possible to amend your comment, Yihui, to provide a bit more context for us n00bs?

Thanks!

cderv commented 3 years ago

Thank you for the feedback @setgree !

I opened a new issue about this from your comment - it is important that all the message are clear !

axrhart commented 3 years ago

FYI with the current development version, users will see a reminder message that tells them to set unsafe to true, if this option has not been set and the markdown renderer is goldmark. It should be much less likely that users get bitten by (lack of) this option silently from now on.

Sorry for kinda necroing this issue, but when am I supposed to see this message? I actually got bitten by not having this Goldmark parameter set to true: if you use the .Rmarkdown workflow then unsafe=false silently strips something like <img src="{{< blogdown/postref >}}index_files/figure-html/example-1.png" width="672" /> from the output when building the site. So the .Rmarkdown variant, out of the box, does no longer work as advertised by the book:

Note that numbered tables, figures, equations, and theorems are also supported.

After a few hours of hunting the error, I figured that it must have something to do with the markdown parsing or rendering options. Then I found that Hugo now uses Goldmark instead of Blackfriday and finally the unsafe parameter, which I more or less switched as a last resort. In this whole process, I've never discovered this closed issue and I would have probably also never have googled for "option unsafe" when it's about a vanishing <img> tag. So maybe the info might need to be presented at a more noticeable place? ^^"

I don't assume that many users will be inclined to use .Rmarkdowns (but I liked it, because I can almost effortlessly include the generated .mds in other projects, so thank you very much for this option!), but maybe it could spare someone some time if they could get this info more easily. :)

yihui commented 3 years ago

@axrhart You may run blogdown::check_site() after you install the latest version of blogdown (which was just released to CRAN last night and will be announced some days later). For more info, please see https://community.rstudio.com/t/92604. From now on, remember "When in doubt, restart and run blogdown::check_site()." :)

axrhart commented 3 years ago

All set! Found the "unsafe" setting for goldmark.

I will, thank you very much! :)

rstudio / blogdown