Helper functions to write Hugo shortcodes using the R syntax

These functions return Hugo shortcodes with the shortcode name and arguments you specify. The closing shortcode will be added only if the inner content is not empty. The function shortcode_html() is essentially shortcode(.type = 'html'). The function shortcodes() is a vectorized version of shortcode(). The paired functions shortcode_open() and shortcode_close() provide an alternative method to open and close shortcodes, which allows inner content be processed safely by Pandoc (e.g., citation keys in the content).

Usage

shortcode(.name, ..., .content = NULL, .type = "markdown")

shortcode_html(...)

shortcodes(..., .sep = "\n")

shortcode_open(...)

shortcode_close(...)

Arguments

.name

The name of the shortcode.

...

All arguments of the shortcode (either all named, or all unnamed). The ... arguments of all other functions are passed to shortcode().

.content

The inner content for the shortcode.

.type

The type of the shortcode: markdown or html.

.sep

The separator between two shortcodes (by default, a newline).

Value

A character string wrapped in htmltools::HTML(); shortcode() returns a string of the form {{% name args %}}, and shortcode_html() returns {{< name args >}}.

Details

These functions can be used in either knitr inline R expressions or code chunks. The returned character string is wrapped in htmltools::HTML(), so rmarkdown will protect it from the Pandoc conversion. You cannot simply write {{< shortcode >}} in R Markdown, because Pandoc is not aware of Hugo shortcodes, and may convert special characters so that Hugo can no longer recognize the shortcodes (e.g. < will be converted to <).

If your document is pure Markdown, you can use the Hugo syntax to write shortcodes, and there is no need to call these R functions.

Note

Since Hugo v0.60, Hugo has switched its default Markdown rendering engine to Goldmark. One consequence is that shortcodes may fail to render. You may enable the unsafe option in the configuration file: https://gohugo.io/getting-started/configuration-markup/#goldmark.

References

https://gohugo.io/extras/shortcodes/

Examples

library(blogdown)

shortcode("tweet", user = "SanDiegoZoo", id = "1453110110599868418")
#> {{% tweet user="SanDiegoZoo" id="1453110110599868418" %}}
# multiple tweets (id's are fake)
shortcodes("tweet", user = "SanDiegoZoo", id = as.character(1:5))
#> {{% tweet user="SanDiegoZoo" id="1" %}}
#> {{% tweet user="SanDiegoZoo" id="2" %}}
#> {{% tweet user="SanDiegoZoo" id="3" %}}
#> {{% tweet user="SanDiegoZoo" id="4" %}}
#> {{% tweet user="SanDiegoZoo" id="5" %}}
shortcode("figure", src = "/images/foo.png", alt = "A nice figure")
#> {{% figure src="/images/foo.png" alt="A nice figure" %}}
shortcode("highlight", "bash", .content = "echo hello world;")
#> {{% highlight "bash" %}}
#> echo hello world;
#> {{% /highlight %}}

shortcode_html("myshortcode", .content = "My <strong>shortcode</strong>.")
#> {{< myshortcode >}}
#> My <strong>shortcode</strong>.
#> {{< /myshortcode >}}

shortcode_open("figure", src = "/images/foo.png")
#> {{% figure src="/images/foo.png" %}}
# This inner text will be *processed* by Pandoc, @Smith2006
shortcode_close("figure")
#> {{% /figure %}}