Add more highlighting support for HTML output

DESCRIPTION

@@ -101,7 +101,8 @@ Suggests:
     vctrs,
     tibble,
     fs,
-    rsconnect
+    rsconnect,
+    downlit (>= 0.2.1)
 SystemRequirements: pandoc (>= 1.14) - http://pandoc.org
 URL: https://github.com/rstudio/rmarkdown
 BugReports: https://github.com/rstudio/rmarkdown/issues

R/html_document.R

@@ -49,9 +49,30 @@
 #'  "darkly", "readable", "spacelab", "united", "cosmo", "lumen", "paper",
 #'  "sandstone", "simplex", or "yeti"). Pass \code{NULL} for no theme (in this
 #'  case you can use the \code{css} parameter to add your own styles).
-#'@param highlight Syntax highlighting style. Supported styles include
-#'  "default", "tango", "pygments", "kate", "monochrome", "espresso", "zenburn",
-#'  "haddock", and "textmate". Pass \code{NULL} to prevent syntax highlighting.
+#'@param highlight Syntax highlight engine and style. See the
+#'  \emph{Highlighting} section below for details.
+#'
+#'  "default" (and "textmate") will use highlightjs as syntax highlighting
+#'  engine instead of Pandoc.
+#'
+#'  Any other value will be passed to Pandoc's
+#'  \href{https://pandoc.org/MANUAL.html#syntax-highlighting}{highlighting
+#'  style}. Pandoc's built-in styles include "tango", "pygments", "kate",
+#'  "monochrome", "espresso", "zenburn", "haddock" and "breezedark". Two custom
+#'   are also included, "arrow", for accessible color scheme and "rstudio",
+#'  to replicate RStudio editor theme. A path to a \samp{.theme} file can also be
+#'  passed to be used as a custom highlighting style for Pandoc. Note that custom
+#'  style are available for Pandoc 2.0+.
+#'
+#'  Pass \code{NULL} to prevent syntax highlighting.
+#'
+#'@param highlight_downlit \code{TRUE} to use the \pkg{downlit} package as
+#'  syntax highlight engine to highlight inline code and R code chunks
+#'  (including providing hyperlinks to function documentation). Only Pandoc
+#'  color schemes are supported with this engine. With \code{highlight}
+#'  "default", it will use the accessible theme called "arrow". To learn more
+#'  about \pkg{downlit} highlighting engine, see
+#'  \url{https://downlit.r-lib.org/}.
 #'@param mathjax Include mathjax. The "default" option uses an https URL from a
 #'  MathJax CDN. The "local" option uses a local version of MathJax (which is
 #'  copied into the output directory). You can pass an alternate URL or pass
@@ -78,6 +99,54 @@
 #'@param extra_dependencies,... Additional function arguments to pass to the
 #'  base R Markdown HTML output formatter \code{\link{html_document_base}}
 #'@return R Markdown output format to pass to \code{\link{render}}
+#'@section Highlighting:
+#'
+#'  Different highlighting engines can be used with a R Markdown HTML documents:
+#'  highlightjs and Pandoc for all languages they support, \pkg{downlit} only
+#'  for R code.
+#'
+#'  highlightjs engine can only be used with the default template (i.e
+#'  \code{template = "default"}) and it has two styles ("default" and
+#'  "textmate"). When activated, a JS script and a CSS file are inserted into
+#'  the output HTML to make it works. For now, this is the default engine for
+#'  the default template - this could change in the future.
+#'
+#'  Pandoc built-in highlighting engine works with any template, default or
+#'  custom, and style can be chosen among the built-in ones ("tango", "pygments",
+#'  "kate", "monochrome", "espresso", "zenburn", "haddock" and "breezedark") or
+#'  among some custom theme passed as ".theme" files (see Details in the
+#'  \href{https://pandoc.org/MANUAL.html#syntax-highlighting}{Pandoc Manual}).
+#'  \pkg{rmarkdown} includes two custom themes to select with \code{highlight}
+#'  parameter:
+#'  \itemize{
+#'  \item{"arrow", an accessible color theme derived from \href{https://www.a11yproject.com/}{optimized for
+#'  accessibility and color contrast}}
+#'  \item{"rstudio", a color scheme close to RStudio's default highlighting and
+#'  highglightjs's textmate.}
+#'  }
+#'  Custom theme are only available for Pandoc 2.0 and above.
+#'
+#'  \href{https://downlit.r-lib.org/}{\pkg{downlit}} is an R package that
+#'  provides a syntax highlighting engine in R. It will also do automatic
+#'  linking of R code (requires internet connectivity). It is activated only if
+#'  \code{highlight_downlit} is \code{TRUE} and will pass after Pandoc engine to
+#'  replace only R code syntax highlighting and will use any selected Pandoc's
+#'  style. Default color scheme is the accessible theme "arrow". If default
+#'  template is used, some CSS is added to get the link introduced by
+#'  autolinking to use the color scheme chosen. If you want to use with a custom
+#'  template, add this to your template:
+#'
+#'  \preformatted{
+#' $if(highlight-downlit)$
+#' <style type="text/css">
+#'   code a:any-link {
+#'    color: inherit; /* use colour from syntax highlighting */
+#'    text-decoration: underline;
+#'    text-decoration-color: #ccc;
+#'   }
+#'  </style>
+#'  $endif$}
+#'
 #'@section Navigation Bars:
 #'
 #'  If you have a set of html documents which you'd like to provide a common
@@ -153,16 +222,19 @@
 #'  Note however that if you choose not to use the "default" HTML template then
 #'  several aspects of HTML document rendering will behave differently:
 #'
-#'  \itemize{ \item{The \code{theme} parameter does not work (you can still
-#'  provide styles using the \code{css} parameter). } \item{For the
-#'  \code{highlight} parameter, the default highlighting style will resolve to
-#'  "pygments" and the "textmate" highlighting style is not available }
-#'  \item{The \code{toc_float} parameter will not work. } \item{The
-#'  \code{code_folding} parameter will not work. } \item{Tabbed sections (as
-#'  described above) will not work.} \item{Navigation bars (as described above)
-#'  will not work. }\item{MathJax will not work if \code{self_contained} is
-#'  \code{TRUE} (these two options can't be used together in normal pandoc
-#'  templates). } }
+#'  \itemize{
+#'  \item{The \code{theme} parameter does not work (you can still provide styles
+#'  using the \code{css} parameter). }
+#'  \item{For the \code{highlight} parameter, the default highlighting engine
+#'  will resolve to Pandoc instead of highlightjs and highlighting style will default to
+#'  "pygments". "textmate" style is not available as related to highlightjs}
+#'  \item{The \code{toc_float} parameter will not work. }
+#'  \item{The \code{code_folding} parameter will not work. }
+#'  \item{Tabbed sections (as described above) will not work.}
+#'  \item{Navigation bars (as described above) will not work. }
+#'  \item{MathJax will not work if \code{self_contained} is \code{TRUE} (these
+#'  two options can't be used together in normal pandoc templates). }
+#'  }
 #'
 #'  Due to the above restrictions, you might consider using the \code{includes}
 #'  parameter as an alternative to providing a fully custom template.
@@ -193,6 +265,7 @@ html_document <- function(toc = FALSE,
                           self_contained = TRUE,
                           theme = "default",
                           highlight = "default",
+                          highlight_downlit = FALSE,
                           mathjax = "default",
                           template = "default",
                           extra_dependencies = NULL,
@@ -277,8 +350,14 @@ html_document <- function(toc = FALSE,
     )
   }
 
-  # highlight
-  args <- c(args, pandoc_html_highlight_args(template, highlight))
+  # highlighting ---------
+  if (highlight_downlit && !xfun::loadable("downlit")) {
+    stop("highlight_downlit=TRUE requires the downlit package to be installed.",
+         call. = FALSE)
+  }
+  args <- c(args,
+            pandoc_html_highlight_args(template, highlight, highlight_downlit)
+  )
 
   # add highlight.js html_dependency if required
   extra_dependencies <- append(
@@ -434,6 +513,20 @@ html_document <- function(toc = FALSE,
     args
   }
 
+  # post-processor that use the output file from pandoc
+  post_processor <- function(metadata, input_file, output_file, clean, verbose) {
+
+    # add a post processor for syntax highlighting with downlit if requested
+    if (highlight_downlit) {
+      output_file <- downlit::downlit_html_path(
+        output_file, output_file,
+        classes = downlit::classes_pandoc()
+      )
+    }
+
+    output_file
+  }
+
   # return format
   output_format(
     knitr = knitr_options_html(fig_width, fig_height, fig_retina, keep_md, dev),
@@ -446,6 +539,7 @@ html_document <- function(toc = FALSE,
     pre_knit = pre_knit,
     post_knit = post_knit,
     pre_processor = pre_processor,
+    post_processor = post_processor,
     on_exit = on_exit,
     base_format = html_document_base(theme = theme,
                                      self_contained = self_contained,
@@ -652,4 +746,3 @@ navbar_link_text <- function(x, ...) {
     tagList(x$text, ...)
 }
 
-

R/md_document.R

@@ -22,7 +22,7 @@
 #'   widely used retina displays, but will also result in the output of
 #'   \code{<img>} tags rather than markdown images due to the need to set the
 #'   width of the image explicitly.
-#' @param ext Extention of the output document (defaults to ".md").
+#' @param ext Extension of the output document (defaults to ".md").
 #' @return R Markdown output format to pass to \code{\link{render}}
 #' @examples
 #' \dontrun{

R/pandoc.R

@@ -551,29 +551,67 @@ unix_mathjax_path <- function() {
 
 
 pandoc_html_highlight_args <- function(template,
-                                       highlight) {
+                                       highlight,
+                                       highlight_downlit = FALSE) {
 
   args <- c()
 
-  if (is.null(highlight)) {
-    args <- c(args, "--no-highlight")
-  }
-  else if (!identical(template, "default")) {
-    if (identical(highlight, "default"))
-      highlight <- "pygments"
-    args <- c(args, "--highlight-style", highlight)
-  }
-  else {
-    highlight <- match.arg(highlight, html_highlighters())
-    if (is_highlightjs(highlight)) {
-      args <- c(args, "--no-highlight")
-      args <- c(args, "--variable", "highlightjs=1")
+  # no highlighting engine
+  if (is.null(highlight)) return(pandoc_highlight_args(NULL))
+
+  # TODO: move out so that it works also for other formats
+  resolve_highlight <- function(highlight) {
+    # if Pandoc built-in highlighter, do no nothing
+    if (highlight %in% highlighters()) return(highlight)
+    if (!pandoc2.0()) {
+      stop("Using a custom highlighting style requires Pandoc 2.0 and above",
+           call. = FALSE)
     }
-    else {
-      args <- c(args, "--highlight-style", highlight)
+    custom <- list(
+      # from distill
+      # https://raw.githubusercontent.com/apreshill/distill/arrow/inst/rmarkdown/templates/distill_article/resources/arrow.theme
+      arrow = pkg_file_highlight("arrow.theme"),
+      # from distill
+      # https://github.com/rstudio/distill/blob/c98d332192ff75f268ddf69bddace34e4db6d89b/inst/rmarkdown/templates/distill_article/resources/rstudio.theme
+      rstudio = pkg_file_highlight("rstudio.theme")
+    )
+    # if not an alias use the provided custom path
+    custom[[highlight]] %||% highlight
+  }
+  highlight <- resolve_highlight(highlight)
+
+  check_highlightjs <- function(highlight, engine) {
+    if (highlight != "default" && is_highlightjs(highlight)) {
+      stop(
+        sprintf(c(
+          "'%s' theme is for highlightjs highlighting engine ",
+          "and can't be used with %s engine."), c(highlight, engine)),
+        call. = FALSE
+      )
     }
   }
 
+  # downlit engine
+  if (highlight_downlit) {
+    check_highlightjs(highlight, "downlit")
+    default <- if (pandoc2.0()) resolve_highlight("arrow") else "pygments"
+    args <- c(
+      pandoc_highlight_args(highlight, default = default),
+      # variable used to insert some css in a Pandoc template
+      pandoc_variable_arg("highlight-downlit")
+    )
+  } else if (template == "default" && is_highlightjs(highlight)) {
+    # highlightjs engine for default template only
+    args <- c(pandoc_highlight_args(NULL),
+              # variable used to insert some css and js
+              # in the Pandoc default template
+              pandoc_variable_arg("highlightjs", "1"))
+  } else {
+    # Pandoc engine
+    check_highlightjs(highlight, "Pandoc")
+    args <- pandoc_highlight_args(highlight, default = "pygments")
+  }
+
   args
 }
 

R/util.R

@@ -80,6 +80,10 @@ pkg_file_lua <- function(filters = NULL, package = "rmarkdown") {
   pandoc_path_arg(files)
 }
 
+pkg_file_highlight <- function(file) {
+  pkg_file("rmarkdown", "highlight", file, mustWork = TRUE)
+}
+
 #' @rdname rmarkdown_format
 #' @export
 from_rmarkdown <- function(implicit_figures = TRUE, extensions = NULL) {