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