mark: Render Markdown to an output format

View source: R/render.R

markR Documentation

Render Markdown to an output format

Description

Render Markdown to an output format via the commonmark package. The function mark_html() is a shorthand of mark(format = 'html', template = TRUE), and mark_latex() is a shorthand of mark(format = 'latex', template = TRUE).

Usage

mark(
  file = NULL,
  output = NULL,
  text = NULL,
  format = c("html", "latex"),
  options = NULL,
  template = FALSE,
  meta = list()
)

mark_html(..., template = TRUE)

mark_latex(..., template = TRUE)

Arguments

file

Path to an input file. If not provided, it is presumed that the text argument will be used instead. This argument can also take a character vector of Markdown text directly. To avoid ambiguity in the latter case, a single character string input will be treated as a file if the file exists. If a string should be treated as Markdown text when it happens to be a file path, wrap it in I().

output

Output file path. If not character, the results will be returned as a character vector. If not specified and the input is a file path, the output file path will have the same base name as the input file, with an extension corresponding to the format argument, e.g., mark('foo.md', format = 'latex') will generate an output file ‘foo.tex’ by default.

text

A character vector of the Markdown text. By default, it is read from file.

format

An output format supported by commonmark, e.g., 'html', 'man', and 'text', etc. See the markdown_*() renderers in commonmark.

options

Options to be passed to the renderer. See markdown_options() for details. This argument can take either a character vector of the form "+option1 option2-option3" (use + or a space to enable an option, and - to disable an option), or a list of the form list(option1 = value1, option2 = value2, ...). A string "+option1" is equivalent to list(option1 = TRUE), and "-option2" means list(option2 = FALSE). Options that do not take logical values must be specified via a list, e.g., list(width = 30).

template

Path to a template file. The default value is getOption('markdown.FORMAT.template', markdown:::pkg_file('resources', 'markdown.FORMAT')) where FORMAT is the output format name (html or latex). It can also take a logical value: TRUE means to use the default template, and FALSE means to generate only a fragment without using any template.

meta

A named list of metadata. Elements in the metadata will be used to fill out the template by their names and values, e.g., list(title = ...) will replace the ⁠$title$⁠ variable in the template. See the Section “YAML metadata” in the vignette vignette('intro', package = 'markdown') for supported variables.

...

Arguments to be passed to mark().

Value

Invisible NULL when output is to a file, otherwise a character vector of the rendered output.

See Also

The spec of GitHub Flavored Markdown: https://github.github.com/gfm/

Examples

library(markdown)
mark(c("Hello _World_!", "", "Welcome to **markdown**."))
# a few corner cases
mark(character(0))
mark("")
# if input happens to be a file path but should be treated as text, use I()
mark(I("This is *not* a file.md"))
# that's equivalent to
mark(text = "This is *not* a file.md")

mark_html("Hello _World_!", template = FALSE)
# write HTML to an output file
mark_html("_Hello_, **World**!", output = tempfile())

mark_latex("Hello _World_!", template = FALSE)

markdown documentation built on June 22, 2024, 9:40 a.m.