Format for converting from R Markdown to GitLab Flavored Markdown.
Usage
gitlab_document(
smart_punctuation = TRUE,
parse_emoji_markup = FALSE,
df_print = "kable",
toc = FALSE,
toc_depth = 6L,
fig_width = 7L,
fig_height = 5L,
dev = "png",
preserve_yaml = FALSE,
add_footnotes_hr = TRUE,
autolink_bare_uris = FALSE,
tex_math_single_backslash = FALSE
)
Arguments
- smart_punctuation
Whether or not to enable Pandoc's
smart
extension which converts straight quotes to curly quotes,---
to an em-dash (—),--
to an en-dash (–), and...
to ellipses (…). It also replaces regular spaces after certain abbreviations such asMr.
with non-breaking spaces.- parse_emoji_markup
Whether to enable Pandoc's
emoji
extension which parses emoji markup (e.g.:smile:
) as Unicode emoticons.- df_print
Method to be used for printing data frames. Valid values include "default", "kable", "tibble", and "paged". The "default" method uses a corresponding S3 method of
print
, typicallyprint.data.frame
. The "kable" method uses theknitr::kable
function. The "tibble" method uses the tibble package to print a summary of the data frame. The "paged" method creates a paginated HTML table (note that this method is only valid for formats that produce HTML). In addition to the named methods you can also pass an arbitrary function to be used for printing data frames. You can disable thedf_print
behavior entirely by setting the optionrmarkdown.df_print
toFALSE
. See Data frame printing section in bookdown book for examples.- toc
Include a table of contents (TOC) automatically generated by Pandoc. Note that the TOC will be placed before the README's body, meaning also before the first Markdown header.
- toc_depth
Depth of headers to include in table of contents
- fig_width
Default width (in inches) for figures
- fig_height
Default height (in inches) for figures
- dev
Graphics device to use for figure output (defaults to png)
- preserve_yaml
Preserve YAML front matter in final document.
- add_footnotes_hr
Whether to add a trailing horizontal rule (
---
) to the final Markdown file if it doesn't already end in one and contains footnotes (currently only checks for Pandoc's reference-style footnotes and not inline footnotes). This improves readability when the file is rendered onGitLab.com
.- autolink_bare_uris
Enable the
autolink_bare_uris
Pandoc Markdown extension which makes all absolute URIs into links, even when not surrounded by pointy braces<...>
.- tex_math_single_backslash
Enable the
tex_math_single_backslash
Pandoc Markdown extension which causes anything between\(
and\)
to be interpreted as inline TeX math, and anything between\[
and\]
to be interpreted as display TeX math. Note: a drawback of this extension is that it precludes escaping(
and[
.
Value
R Markdown output format intended to be fed to rmarkdown::render()
.
Details
This is the GitLab equivalent to the github_document
R Markdown
output format. It basically ensures Pandoc is called with a custom set of options optimized for
maximum compatibility with GitLab Flavored Markdown.
Caveats regarding GitLab-Flavored-Markdown-specific features
GitLab Flavored Markdown extends the CommonMark Markdown specification with a bunch of special features. To be able to properly make use of them, observe the following points:
For inline diffs, only use curly braces (
{}
), not square brackets ([]
). The latter will be escaped by Pandoc during conversion and thus not recognized by GitLab as starting/ending an inline diff.You have to set
smart_punctuation = FALSE
in order to leave certain special GitLab references (like commit range comparisons) untouched for GitLab to interpret them correctly.All the special GitLab references for snippets and labels that start with a tilde (
~
) or a dollar sign ($
) won't work because these characters will be escaped by Pandoc during conversion.The
[[_TOC_]]
tag to let GitLab generate a table of contents won't work because it will be escaped by Pandoc during conversion. You can let Pandoc generate the TOC instead by settingtoc = TRUE
.Multiline blockquotes won't work because the fence delimiters
>>>
will be escaped by Pandoc during conversion.
Examples
# \donttest{
tmp_file <- fs::file_temp()
download.file(url = "https://gitlab.com/rpkg.dev/pal/-/raw/master/Rmd/pal.Rmd",
destfile = tmp_file,
quiet = TRUE,
mode = "wb")
rmarkdown::render(input = tmp_file,
output_format = pal::gitlab_document(),
quiet = TRUE) |>
brio::read_lines() |>
length()# }
#> [1] 4228