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