Utility Functions

gitlab_document

R Documentation

Convert to GitLab Flavored Markdown

Description

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 as `Mr.` 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`, typically `print.data.frame`. The "kable" method uses the `knitr::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 the `df_print` behavior entirely by setting the option `rmarkdown.df_print` to `FALSE`. 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 on `GitLab.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 `[`.

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 setting toc = TRUE.
Multiline blockquotes won't work because the fence delimiters ⁠>>>⁠ will be escaped by Pandoc during conversion.

Value

R Markdown output format intended to be fed to rmarkdown::render().

Examples


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()

salim-b/pal documentation built on Feb. 28, 2025, 6:51 p.m.