mark: 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'), and mark_latex() is a shorthand of mark(format = 'latex').

Usage

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

Value

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

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 only when the file exists or it has a file extension. If a string happens to have a “file extension” and should be treated as Markdown text instead, wrap it in I().
output: Output file path. If not character, the results will be returned as a character vector.
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 all possible options. 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 ‘Details’ section for supported variables.
...: For mark_latex(), arguments to be passed to mark(). For mark_html(), additional arguments for backward-compatibility with previous versions of markdown. These are no longer recommended. For example, the stylesheet argument should be replaced by the css variable in meta, and the fragment.only = TRUE argument should be specified via options = '-standalone' instead.

Details

Supported variables in metadata for both HTML and HTML templates (the string FORMAT below is the output format name, i.e., html or latex):

header-includes, include-before, include-after: Either a vector of code (HTML/LaTeX) or a code file to be included in the header, before the body, or after the body of the output. For header-include, the default value is taken from getOption('markdown.FORMAT.header') if not provided in meta.
title: The document title.

Variables for the HTML template:

css: Either a vector of CSS code or a file containing CSS to be included in the output. The default value is getOption('markdown.html.css', markdown:::pkg_file('resources', 'markdown.css')), i.e., it can be set via the global option markdown.html.css.
highlight: JavaScript code for syntax-highlighting code blocks. By default, the highlight.js library is used.
math: JavaScript code for rendering LaTeX math. By default, MathJax is used.

Variables for the LaTeX template:

classoption: A string containing options for the document class.
documentclass: The document class (by default, 'article').

Note that you can use either underscores or hyphens in the variable names. Underscores will be normalized to hyphens internally, e.g., header_includes will be converted to header-includes. This means if you use a custom template, you must use hyphens instead of underscores as separators in variable names in the template.

Examples

Run this code

library(markdown)
mark(c("Hello _World_!", "", "Welcome to **markdown**."))
# a few corner cases
mark(character(0))
mark("")
# if input looks like file 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_!", options = "-standalone")
# write HTML to an output file
mark_html("_Hello_, **World**!", output = tempfile())