Render Markdown, R Markdown, and R scripts

The function fuse() runs code from code chunks and inline code expressions in R Markdown, interweaves the results with the rest of text in the input to intermediate Markdown output (which is similar to what knitr::knit() does), and renders the Markdown output through mark() to the final output format, such as HTML or LaTeX (similar to rmarkdown::render()). It also works on R scripts in a way similar to knitr::spin(). The function fiss() extracts code from the input, and is similar to knitr::purl().

The function mark() renders Markdown to an output format via the commonmark package.

Usage

fuse(input, output = NULL, text = NULL, envir = parent.frame(), quiet = FALSE)

fiss(input, output = ".R", text = NULL)

mark(input, output = NULL, text = NULL, options = NULL, meta = list())

Arguments

input: A character vector to provide the input file path or text. If not provided, the text argument must be provided instead. The input vector will be treated as a file path if it is a single string, and points to an existing file or has a filename extension. In other cases, the vector will be treated as the text argument input. To avoid ambiguity, if a string should be treated as text input when it happens to be an existing file path or has an extension, wrap it in I(), or simply use the text argument instead.
output: An output file path or a filename extension (e.g., .html, .tex, .xml, .man, .markdown, or .txt). In the latter case, the output file path will use the extension on the same base filename as the input file if the input is a file. If output is not character (e.g., NA), the results will be returned as a character vector instead of being written to a file. If output is NULL or an extension, 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 output format. The output format is retrieved from the first value in the output field of the YAML metadata of the input (e.g., html will generate HTML output). The output argument can also take an output format name (possible values are html, latex, xml, man, commonmark, and text). If no output format is detected or provided, the default is HTML.
text: A character vector as the text input. By default, it is read from the input file if provided.
envir: An environment in which the code is to be evaluated. It can be accessed via fuse_env() inside fuse().
quiet: If TRUE, do not show the progress bar. If FALSE, the progress bar will be shown after a number of seconds, which can be set via a global option litedown.progress.delay (the default is 2). THe progress bar output can be set via a global option litedown.progress.output (the default is stderr()).
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).
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 documentation for supported variables.

Value

The output file path if output is written to a file, otherwise a character vector of the rendered output (wrapped in xfun::raw_string() for clearer printing).

Note

For fuse(), you can generate the intermediate Markdown output via output = '.md' or output = 'markdown' without further calling mark().

Examples

library(litedown)
doc = c("```{r}", "1 + 1", "```", "", "$\\pi$ = `{r} pi`.")
fuse(doc)
#> <pre><code class="language-r">1 + 1
#> </code></pre>
#> <pre><code>#&gt; [1] 2
#> </code></pre>
#> <p>\(\pi\) = 3.14.</p>
fuse(doc, ".tex")
#> \begin{verbatim}
#> 1 + 1
#> \end{verbatim}
#> 
#> \begin{verbatim}
#> #> [1] 2
#> \end{verbatim}
#> 
#> \(\pi\) = 3.14.
fiss(doc)
#> 1 + 1
#> 

mark(c("Hello _World_!", "", "Welcome to **litedown**."))
#> <p>Hello <em>World</em>!</p>
#> <p>Welcome to <strong>litedown</strong>.</p>
# if input appears to be a file path but should be treated as text, use I()
mark(I("This is *not* a file.md"))
#> <p>This is <em>not</em> a file.md</p>
# that's equivalent to
mark(text = "This is *not* a file.md")
#> <p>This is <em>not</em> a file.md</p>

# output to a file
(mark("_Hello_, **World**!", output = tempfile()))
#> [1] "/tmp/RtmpLWxjAb/file17b49d22fec4e6"

# convert to other formats
mark("Hello _World_!", ".tex")
#> Hello \emph{World}!
mark("Hello _**`World`**_!", "xml")
#> <?xml version="1.0" encoding="UTF-8"?>
#> <!DOCTYPE document SYSTEM "CommonMark.dtd">
#> <document xmlns="http://commonmark.org/xml/1.0">
#>   <paragraph>
#>     <text xml:space="preserve">Hello </text>
#>     <emph>
#>       <strong>
#>         <code xml:space="preserve">World</code>
#>       </strong>
#>     </emph>
#>     <text xml:space="preserve">!</text>
#>   </paragraph>
#> </document>
mark("Hello _**`World`**_!", "text")
#> Hello World!