1#' Convert to GitHub Flavored Markdown
2#'
3#' Format for converting from R Markdown to GitHub Flavored Markdown.
4#'
5#' @inheritParams output_format
6#' @inheritParams html_document
7#' @inheritParams md_document
8#'
9#' @param hard_line_breaks \code{TRUE} to genreate markdown that uses a simple
10#'   newline to represent a line break (as opposed to two-spaces and a newline).
11#'
12#' @param html_preview \code{TRUE} to also generate an HTML file for the purpose of
13#'   locally previewing what the document will look like on GitHub.
14#'
15#' @return R Markdown output format to pass to \code{\link{render}}
16#'
17#' @export
18github_document <- function(toc = FALSE,
19                            toc_depth = 3,
20                            fig_width = 7,
21                            fig_height = 5,
22                            dev = 'png',
23                            df_print = "default",
24                            includes = NULL,
25                            md_extensions = NULL,
26                            hard_line_breaks = TRUE,
27                            pandoc_args = NULL,
28                            html_preview = TRUE) {
29
30  # add special markdown rendering template to ensure we include the title fields
31  pandoc_args <- c(
32    pandoc_args, "--template", pandoc_path_arg(rmarkdown_system_file(
33      "rmarkdown/templates/github_document/resources/default.md"))
34  )
35
36  pandoc2 <- pandoc2.0()
37  # use md_document as base
38  variant <- if (pandoc2) "gfm" else "markdown_github"
39  if (!hard_line_breaks) variant <- paste0(variant, "-hard_line_breaks")
40
41  # turn off ASCII identifiers
42  variant <- paste0(variant, "-ascii_identifiers")
43
44  format <- md_document(
45    variant = variant, toc = toc, toc_depth = toc_depth,
46    fig_width = fig_width, fig_height = fig_height, dev = dev,
47    df_print = df_print, includes = includes, md_extensions = md_extensions,
48    pandoc_args = pandoc_args
49  )
50
51  # remove 'ascii_identifiers' if necessary -- required to ensure that
52  # TOC links are correctly generated on GitHub
53  format$pandoc$from <- gsub("+ascii_identifiers", "", format$pandoc$from, fixed = TRUE)
54
55  # add a post processor for generating a preview if requested
56  if (html_preview) {
57    format$post_processor <- function(metadata, input_file, output_file, clean, verbose) {
58
59      css <- pandoc_path_arg(rmarkdown_system_file(
60        "rmarkdown/templates/github_document/resources/github.css"))
61      # provide a preview that looks like github
62      args <- c(
63        "--standalone", "--self-contained", "--highlight-style", "pygments",
64        "--template", pandoc_path_arg(rmarkdown_system_file(
65          "rmarkdown/templates/github_document/resources/preview.html")),
66        "--variable", paste0("github-markdown-css:", css),
67        "--email-obfuscation", "none", # no email obfuscation
68        if (pandoc2) c("--metadata", "pagetitle=PREVIEW")  # HTML5 requirement
69      )
70
71      # run pandoc
72      preview_file <- file_with_ext(output_file, "html")
73      pandoc_convert(
74        input = output_file, to = "html", from = variant, output = preview_file,
75        options = args, verbose = verbose
76      )
77
78      # move the preview to the preview_dir if specified
79      preview_dir <- Sys.getenv("RMARKDOWN_PREVIEW_DIR", unset = NA)
80      if (!is.na(preview_dir)) {
81        relocated_preview_file <- tempfile("preview-", preview_dir, ".html")
82        file.copy(preview_file, relocated_preview_file)
83        file.remove(preview_file)
84        preview_file <- relocated_preview_file
85      }
86
87      if (verbose) message("\nPreview created: ", preview_file)
88
89      output_file
90    }
91  }
92
93  format  # return format
94}
95