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

@@ -52,6 +52,10 @@
 #'@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_downlit \code{TRUE} to use the \pkg{downlit} package to
+#'  highlight R code (including providing hyperlinks to function documentation).
+#'  Only pandoc highlighting is supported, so with \code{highlight} parameter to
+#'  "default" or "textmate", "pygments" will be used.
 #'@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
@@ -193,6 +197,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 +282,18 @@ html_document <- function(toc = FALSE,
     )
   }
 
-  # highlight
-  args <- c(args, pandoc_html_highlight_args(template, highlight))
+  # highlighting ---------
+  if (highlight_downlit) {
+    if (!xfun::loadable("downlit")) {
+      warning("highlight_downlit=TRUE requires the downlit package",
+              "downlit highlighting won't be applied",
+              "and no function linking will be done.", call. = FALSE)
+      highlight_downlit <- FALSE
+    }
+  }
+  args <- c(args,
+            pandoc_html_highlight_args(template, highlight, highlight_downlit)
+  )
 
   # add highlight.js html_dependency if required
   extra_dependencies <- append(
@@ -434,6 +449,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 +475,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,

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,25 +551,34 @@ unix_mathjax_path <- function() {
 
 
 pandoc_html_highlight_args <- function(template,
-                                       highlight) {
-
+                                       highlight,
+                                       highlight_downlit = FALSE) {
   args <- c()
-
   if (is.null(highlight)) {
+    # deactivate all highlighting if requesting
     args <- c(args, "--no-highlight")
-  }
-  else if (!identical(template, "default")) {
-    if (identical(highlight, "default"))
-      highlight <- "pygments"
+  } else if (highlight_downlit) {
+    # use pandoc highlight and add custom css
+    if (is_highlightjs(highlight)) {
+      # default to accessible theme a11y - copied from distill
+      # https://github.com/rstudio/distill/blob/c98d332192ff75f268ddf69bddace34e4db6d89b/inst/rmarkdown/templates/distill_article/resources/a11y.theme
+      highlight <- pkg_file_highlight("a11y.theme")
+    }
     args <- c(args, "--highlight-style", highlight)
-  }
-  else {
+    args <- c(args, "--variable", "highlight-downlit=1")
+  } else if (!identical(template, "default")) {
+    # Use requested pandoc highlighting for non default pandoc template
+    if (identical(highlight, "default")) highlight <- "pygments"
+    args <- c(args, "--highlight-style", highlight)
+  } else {
+    # for default template only - Pandoc .theme file not supported
     highlight <- match.arg(highlight, html_highlighters())
     if (is_highlightjs(highlight)) {
+      # use highlightjs by default and not pandoc highlighting
       args <- c(args, "--no-highlight")
       args <- c(args, "--variable", "highlightjs=1")
-    }
-    else {
+    } else {
+      # or specified highlight style
       args <- c(args, "--highlight-style", highlight)
     }
   }

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) {

inst/rmarkdown/highlight/a11y.theme

@@ -0,0 +1,211 @@
+{
+    "text-color": null,
+    "background-color": null,
+    "line-number-color": "#aaaaaa",
+    "line-number-background-color": null,
+    "text-styles": {
+        "Other": {
+            "text-color": "#007faa",
+            "background-color": null,
+            "bold": false,
+            "italic": false,
+            "underline": false
+        },
+        "Attribute": {
+            "text-color": "#7d9029",
+            "background-color": null,
+            "bold": false,
+            "italic": false,
+            "underline": false
+        },
+        "SpecialString": {
+            "text-color": "#bb6688",
+            "background-color": null,
+            "bold": false,
+            "italic": false,
+            "underline": false
+        },
+        "Annotation": {
+            "text-color": "#545454",
+            "background-color": null,
+            "bold": true,
+            "italic": false,
+            "underline": false
+        },
+        "Function": {
+            "text-color": "#4254A7",
+            "background-color": null,
+            "bold": false,
+            "italic": false,
+            "underline": false
+        },
+        "String": {
+            "text-color": "#008000",
+            "background-color": null,
+            "bold": false,
+            "italic": false,
+            "underline": false
+        },
+        "ControlFlow": {
+            "text-color": "#007faa",
+            "background-color": null,
+            "bold": true,
+            "italic": false,
+            "underline": false
+        },
+        "Operator": {
+            "text-color": "#696969",
+            "background-color": null,
+            "bold": false,
+            "italic": false,
+            "underline": false
+        },
+        "Error": {
+            "text-color": "#ff0000",
+            "background-color": null,
+            "bold": true,
+            "italic": false,
+            "underline": false
+        },
+        "BaseN": {
+            "text-color": "#a1024a",
+            "background-color": null,
+            "bold": false,
+            "italic": false,
+            "underline": false
+        },
+        "Alert": {
+            "text-color": "#ff0000",
+            "background-color": null,
+            "bold": true,
+            "italic": false,
+            "underline": false
+        },
+        "Variable": {
+            "text-color": "#19177c",
+            "background-color": null,
+            "bold": false,
+            "italic": false,
+            "underline": false
+        },
+        "BuiltIn": {
+            "text-color": null,
+            "background-color": null,
+            "bold": false,
+            "italic": false,
+            "underline": false
+        },
+        "Extension": {
+            "text-color": null,
+            "background-color": null,
+            "bold": false,
+            "italic": false,
+            "underline": false
+        },
+        "Preprocessor": {
+            "text-color": "#bc7a00",
+            "background-color": null,
+            "bold": false,
+            "italic": false,
+            "underline": false
+        },
+        "Information": {
+            "text-color": "#545454",
+            "background-color": null,
+            "bold": true,
+            "italic": false,
+            "underline": false
+        },
+        "VerbatimString": {
+            "text-color": "#008000",
+            "background-color": null,
+            "bold": false,
+            "italic": false,
+            "underline": false
+        },
+        "Warning": {
+            "text-color": "#545454",
+            "background-color": null,
+            "bold": true,
+            "italic": true,
+            "underline": false
+        },
+        "Documentation": {
+            "text-color": "#ba2121",
+            "background-color": null,
+            "bold": false,
+            "italic": true,
+            "underline": false
+        },
+        "Import": {
+            "text-color": null,
+            "background-color": null,
+            "bold": false,
+            "italic": false,
+            "underline": false
+        },
+        "Char": {
+            "text-color": "#008000",
+            "background-color": null,
+            "bold": false,
+            "italic": false,
+            "underline": false
+        },
+        "DataType": {
+            "text-color": "#aa5d00",
+            "background-color": null,
+            "bold": false,
+            "italic": false,
+            "underline": false
+        },
+        "Float": {
+            "text-color": "#a1024a",
+            "background-color": null,
+            "bold": false,
+            "italic": false,
+            "underline": false
+        },
+        "Comment": {
+            "text-color": "#545454",
+            "background-color": null,
+            "bold": false,
+            "italic": false,
+            "underline": false
+        },
+        "CommentVar": {
+            "text-color": "#545454",
+            "background-color": null,
+            "bold": true,
+            "italic": true,
+            "underline": false
+        },
+        "Constant": {
+            "text-color": "#d91e18",
+            "background-color": null,
+            "bold": false,
+            "italic": false,
+            "underline": false
+        },
+        "SpecialChar": {
+            "text-color": "#008000",
+            "background-color": null,
+            "bold": false,
+            "italic": false,
+            "underline": false
+        },
+        "DecVal": {
+            "text-color": "#a1024a",
+            "background-color": null,
+            "bold": false,
+            "italic": false,
+            "underline": false
+        },
+        "Keyword": {
+            "text-color": "#007faa",
+            "background-color": null,
+            "bold": true,
+            "italic": false,
+            "underline": false
+        }
+    }
+}

inst/rmd/h/default.html

@@ -62,6 +62,17 @@
 </script>
 $endif$
 
+$if(highlight-downlit)$
+<style type="text/css">
+  /* from bookdown::bs4_book() css */
+  code a:any-link {
+    color: inherit; /* use colour from syntax highlighting */
+    text-decoration: underline;
+    text-decoration-color: #ccc;
+  }
+</style>
+$endif$
+
 $if(highlighting-css)$
 <style type="text/css">code{white-space: pre;}</style>
 <style type="text/css" data-origin="pandoc">