1#' Convert to a markdown document 2#' 3#' Format for converting from R Markdown to another variant of markdown (e.g. 4#' strict markdown or github flavored markdown) 5#' 6#' @inheritParams html_document 7#' 8#' @param variant Markdown variant to produce (defaults to "markdown_strict"). 9#' Other valid values are "markdown_github", "markdown_mmd", 10#' markdown_phpextra", or even "markdown" (which produces pandoc markdown). 11#' You can also compose custom markdown variants, see the 12#' \href{http://pandoc.org/README.html}{pandoc online documentation} 13#' for details. 14#' 15#' @param preserve_yaml Preserve YAML front matter in final document. 16#' 17#' @param fig_retina Scaling to perform for retina displays. Defaults to 18#' \code{NULL} which performs no scaling. A setting of 2 will work for all 19#' widely used retina displays, but will also result in the output of 20#' \code{<img>} tags rather than markdown images due to the need to set the 21#' width of the image explicitly. 22#' 23#' @return R Markdown output format to pass to \code{\link{render}} 24#' 25#' @details 26#' 27#' See the \href{http://rmarkdown.rstudio.com/markdown_document_format.html}{online 28#' documentation} for additional details on using the \code{md_document} format. 29#' 30#' R Markdown documents can have optional metadata that is used to generate a 31#' document header that includes the title, author, and date. For more details 32#' see the documentation on R Markdown \link[=rmd_metadata]{metadata}. 33#' 34#' R Markdown documents also support citations. You can find more information on 35#' the markdown syntax for citations in the 36#' \href{http://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html}{Bibliographies 37#' and Citations} article in the online documentation. 38#' 39#' @examples 40#' \dontrun{ 41#' 42#' library(rmarkdown) 43#' 44#' render("input.Rmd", md_document()) 45#' 46#' render("input.Rmd", md_document(variant = "markdown_github")) 47#' } 48#' 49#' @export 50md_document <- function(variant = "markdown_strict", 51 preserve_yaml = FALSE, 52 toc = FALSE, 53 toc_depth = 3, 54 fig_width = 7, 55 fig_height = 5, 56 fig_retina = NULL, 57 dev = 'png', 58 df_print = "default", 59 includes = NULL, 60 md_extensions = NULL, 61 pandoc_args = NULL) { 62 63 # base pandoc options for all markdown output 64 args <- c(if (variant != "markdown" && !preserve_yaml) "--standalone") 65 66 # table of contents 67 args <- c(args, pandoc_toc_args(toc, toc_depth)) 68 69 # content includes 70 args <- c(args, includes_to_pandoc_args(includes)) 71 72 # pandoc args 73 args <- c(args, pandoc_args) 74 75 # add post_processor for yaml preservation 76 if (preserve_yaml) { 77 post_processor <- function(metadata, input_file, output_file, clean, verbose) { 78 input_lines <- readLines(input_file, warn = FALSE) 79 partitioned <- partition_yaml_front_matter(input_lines) 80 if (!is.null(partitioned$front_matter)) { 81 output_lines <- c(partitioned$front_matter, 82 "", 83 readLines(output_file, warn = FALSE)) 84 writeLines(output_lines, output_file, useBytes = TRUE) 85 } 86 output_file 87 } 88 } else { 89 post_processor <- NULL 90 } 91 92 # return format 93 output_format( 94 knitr = knitr_options_html(fig_width, fig_height, fig_retina, FALSE, dev), 95 pandoc = pandoc_options(to = variant, 96 from = from_rmarkdown(extensions = md_extensions), 97 args = args, 98 ext = '.md'), 99 clean_supporting = FALSE, 100 df_print = df_print, 101 post_processor = post_processor 102 ) 103} 104