Support custom highlight theme in other formats

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: rmarkdown
 Title: Dynamic Documents for R
-Version: 2.11.7
+Version: 2.11.8
 Authors@R: c(
     person("JJ", "Allaire", , "[email protected]", role = "aut"),
     person("Yihui", "Xie", , "[email protected]", role = c("aut", "cre"), comment = c(ORCID = "0000-0003-0645-5666")),

NEWS.md

@@ -1,10 +1,10 @@
 rmarkdown 2.12
 ================================================================================
 
-- Improved the highlighting mechanism for HTML outputs: 
+- Improved the highlighting mechanism in formats that supports `highlight` argument: 
   * It is now possible to pass a custom theme file `.theme` in `highlight` argument for customizing the [syntax highlighting style used by Pandoc](https://pandoc.org/MANUAL.html#syntax-highlighting). 
   * In addition to Pandoc's own supported themes, two more themes are bundled in the package:  `highlight: arrow` a theme [optimized for accessibility and color constrast](https://www.a11yproject.com/) (thanks to @apreshill), and `highlight: rstudio` to mimic the RStudio editor theme.
-  * Added optional [downlit](https://downlit.r-lib.org/) support in `html_document()` for R syntax highlighting and autolinking. Use `highlight_downlit = TRUE` to activate it (same argument as in **distill**). This features require the **downlit** package. 
+  * For HTML output only, added optional [downlit](https://downlit.r-lib.org/) support in `html_document()` for R syntax highlighting and autolinking. Use `highlight_downlit = TRUE` to activate it (same argument as in **distill**). This features require the **downlit** package. 
 
 - Added a global option `rmarkdown.html_dependency.header_attr` (`TRUE` by default). It can be set to `FALSE` to opt-out the HTML dependency `html_dependency_header_attrs()` in documents based on `html_document_base()` (thanks, @salim-b rstudio/bookdown#865, @maelle r-lib/downlit#1538).
 

R/beamer_presentation.R

@@ -106,8 +106,7 @@ beamer_presentation <- function(toc = FALSE,
     args <- c(args, pandoc_variable_arg("fonttheme", fonttheme))
 
   # highlighting
-  if (!is.null(highlight))
-    highlight <- match.arg(highlight, highlighters())
+  if (!is.null(highlight)) highlight <- resolve_highlight(highlight, highlighters())
   args <- c(args, pandoc_highlight_args(highlight))
 
   # latex engine

R/html_document.R

@@ -64,15 +64,15 @@
 #'  "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".
+#'  Any other value will be passed as Pandoc's highlighting style. Pandoc's
+#'  built-in styles include "tango", "pygments", "kate", "monochrome",
+#'  "espresso", "zenburn", "haddock" and "breezedark".
 #'
 #'  Two custom styles are also included, "arrow", an accessible color scheme,
 #'  and "rstudio", which mimics the default IDE theme. Alternatively, supply a
-#'  path to a \samp{.theme} to use a custom Pandoc style. Note that custom theme
-#'  requires Pandoc 2.0+.
+#'  path to a \samp{.theme} to use
+#'  \href{https://pandoc.org/MANUAL.html#syntax-highlighting}{a custom Pandoc
+#'  style}. Note that custom theme requires Pandoc 2.0+.
 #'
 #'  Pass \code{NULL} to prevent syntax highlighting.
 #'

R/pandoc.R

@@ -564,26 +564,7 @@ pandoc_html_highlight_args <- function(template,
   # 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)
-    }
-    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)
+  highlight <- resolve_highlight(highlight, html_highlighters())
 
   check_highlightjs <- function(highlight, engine) {
     if (highlight != "default" && is_highlightjs(highlight)) {
@@ -624,6 +605,38 @@ is_highlightjs <- function(highlight) {
   !is.null(highlight) && (highlight %in% c("default", "textmate"))
 }
 
+resolve_highlight <- function(highlight, supported = highlighters()) {
+  # for backward compatibility, partial match still need to work
+  i <- pmatch(highlight, supported, nomatch = 0L)
+  if (i > 0L) return(supported[i])
+
+  # Otherwise it could be a custom (built-in) .theme file
+  if (!pandoc2.0()) {
+    stop("Using a custom highlighting style requires Pandoc 2.0 and above",
+         call. = FALSE)
+  }
+  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
+  highlight <- custom[[highlight]] %||% highlight
+  # Check for extension or give informative error otherwise
+  if (!identical(xfun::file_ext(highlight), "theme")) {
+    msg <- c(
+      sprintf("`highlight` argument must be one of %s",
+              knitr::combine_words(c(supported, names(custom)), and = " or ", before = "`")),
+      " or a file with extension `.theme`."
+    )
+    stop(msg, call. = FALSE)
+  }
+  highlight
+}
+
 #' Find the \command{pandoc} executable
 #'
 #' Searches for the \command{pandoc} executable in a few places and use the

R/pdf_document.R

@@ -46,9 +46,18 @@
 #'   \command{ghostscript} to be installed. By default, \code{fig_crop = TRUE}
 #'   if these two tools are available.
 #' @param dev Graphics device to use for figure output (defaults to pdf)
-#' @param highlight Syntax highlighting style. Supported styles include
-#'   "default", "tango", "pygments", "kate", "monochrome", "espresso",
-#'   "zenburn", and "haddock". Pass \code{NULL} to prevent syntax highlighting.
+#' @param highlight Syntax highlighting style passed to Pandoc.
+#'
+#'  Supported built-in styles include "default", "tango", "pygments", "kate",
+#'  "monochrome", "espresso", "zenburn", "haddock", and "breezedark".
+#'
+#'   Two custom styles are also included, "arrow", an accessible color scheme,
+#'   and "rstudio", which mimics the default IDE theme. Alternatively, supply a
+#'   path to a \samp{.theme} file to use
+#'   \href{https://pandoc.org/MANUAL.html#syntax-highlighting}{a custom Pandoc
+#'   style}. Note that custom theme requires Pandoc 2.0+.
+#'
+#'   Pass \code{NULL} to prevent syntax highlighting.
 #' @param keep_tex Keep the intermediate tex file used in the conversion to PDF
 #' @param latex_engine LaTeX engine for producing PDF output. Options are
 #'   "pdflatex", "lualatex", "xelatex" and "tectonic".
@@ -127,8 +136,7 @@ pdf_document <- function(toc = FALSE,
     args <- c(args, "--number-sections")
 
   # highlighting
-  if (!is.null(highlight))
-    highlight <- match.arg(highlight, highlighters())
+  if (!is.null(highlight)) highlight <- resolve_highlight(highlight, highlighters())
   args <- c(args, pandoc_highlight_args(highlight))
 
   # latex engine

R/slidy_presentation.R

@@ -119,6 +119,7 @@ slidy_presentation <- function(number_sections = FALSE,
     args <- c()
 
     # highlight
+    if (!is.null(highlight)) highlight <- resolve_highlight(highlight, highlighters())
     args <- c(args, pandoc_highlight_args(highlight, default = "pygments"))
 
     # return additional args

R/word_document.R

@@ -71,8 +71,7 @@ word_document <- function(toc = FALSE,
   }
 
   # highlighting
-  if (!is.null(highlight))
-    highlight <- match.arg(highlight, highlighters())
+  if (!is.null(highlight)) highlight <- resolve_highlight(highlight, highlighters())
   args <- c(args, pandoc_highlight_args(highlight))
 
   # reference docx

tests/testthat/test-pandoc.R

@@ -9,6 +9,22 @@ test_that("build highlight args for pandoc correctly", {
   expect_equal(pandoc_highlight_args("zenburn"), hl_style("zenburn"))
 })
 
+test_that("Detect if a theme file is providing in highlight", {
+  expect_equal(resolve_highlight("default"), "default")
+  expect_equal(resolve_highlight("breezedark"), "breezedark")
+  expect_equal(resolve_highlight("breez"), "breezedark")
+  expect_error(resolve_highlight("textmate"), "must be one of")
+  expect_equal(
+    resolve_highlight("textmate", html_highlighters()), "textmate"
+  )
+  if (pandoc_available("2.0")) {
+    expect_equal(resolve_highlight("arrow"), pkg_file_highlight("arrow.theme"))
+    expect_equal(resolve_highlight("custom.theme"), "custom.theme")
+    expect_error(resolve_highlight("custom.json"), "a file with extension")
+  } else {
+    expect_error(resolve_highlight("arrow"), "requires Pandoc 2.0")
+  }
+})
 
 test_that("Correct HTML highlighting argument as requested", {
   # helpers