markdownToHTML: Render markdown to HTML

Description

markdownToHTML transforms the markdown text provided by the user in either the file or text variable. The HTML transformation is either written to the output file or returned to the user as a character vector.

Usage

markdownToHTML(
  file,
  output = NULL,
  text = NULL,
  options = getOption("markdown.HTML.options"),
  extensions = getOption("markdown.extensions"),
  title = "",
  stylesheet = getOption("markdown.HTML.stylesheet"),
  header = getOption("markdown.HTML.header"),
  template = getOption("markdown.HTML.template"),
  fragment.only = FALSE,
  encoding = "UTF-8"
)

Value

Invisible NULL when output is to a file, and a character vector otherwise.

Arguments

file: a character string giving the pathname of the file to read from. If it is omitted from the argument list, then it is presumed that the text argument will be used instead.
output: a character string giving the pathname of the file to write to. If it is omitted (NULL), then it is presumed that the user expects the results returned as a character vector.
text: a character vector containing the markdown text to transform (each element of this vector is treated as a line in a file).
options: options that are passed to the renderer. see markdownHTMLOptions.
extensions: options that are passed to the markdown engine. See markdownExtensions.
title: The HTML title.
stylesheet: either valid CSS or a file containing CSS. will be included in the output.
header: either valid HTML or a file containing HTML will be included in the header of the output.
template: an HTML file used as template.
fragment.only: Whether or not to produce an HTML fragment without the HTML header and body tags, CSS, and Javascript components.
encoding: ignored (always assumes the file is encoded in UTF-8).

Details

Three notable HTML options have been added to support collaborative reproducible research. They are as follows:

Latex math expressions enclosed by one of the block level syntaxes, $latex ... $ , $$ ... $$, or \[ ... \], or one of the inline syntaxes, $...$, or $ ... $, will be rendered in real-time by the MathJax Javascript library.
R code blocks enclosed between ```r and ``` will automatically be syntax highlighted.
Any local images linked using the <img> tag will be base64 encoded and included in the output HTML.

See the DETAILS section below and markdownHTMLOptions for more information.

There are two basic modes to markdownToHTML determined by the value of the fragment.only argument:

When FALSE, markdownToHTML creates well-formed stand-alone HTML pages complete with HTML header, title, and body tags. The default template used for this mode may be found here:

system.file('resources', 'markdown.html', package = 'markdown')

Also, markdownToHTML will automatically determine whether or not mathjax and R code highlighting are needed and will include the appropriate Javascript libraries in the output. Thus, there's no need to explicitly set the 'mathjax' or 'highlight_code' options (see markdownHTMLOptions for more details).

When fragment.only is TRUE, nothing extra is added.

Examples

Run this code

(markdownToHTML(text = "Hello World!", fragment.only = TRUE))
(markdownToHTML(file = NULL, text = "_text_ will override _file_", fragment.only = TRUE))
# write HTML to an output file
markdownToHTML(text = "_Hello_, **World**!", output = tempfile())