Skip to contents

Convert to GitLab Flavored Markdown

Source: R/pal.gen.R
gitlab_document.Rd

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.

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 setting toc = 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] 4053