Add an argument lua_filters to pandoc_options() to store them in the output format object (#1899)

close #1897

Author: cderv

NAMESPACE

@@ -62,6 +62,7 @@ export(pandoc_exec)
 export(pandoc_highlight_args)
 export(pandoc_include_args)
 export(pandoc_latex_engine_args)
+export(pandoc_lua_filter_args)
 export(pandoc_metadata_arg)
 export(pandoc_options)
 export(pandoc_path_arg)

NEWS.md

@@ -1,6 +1,11 @@
 rmarkdown 2.4
 ================================================================================
 
+- Lua filters handling has been improved internally with some user-facing changes (#1899):
+    - New exported function `pandoc_lua_filter_args()` to return the Pandoc command-line argument to add a Lua filter.
+    - New argument `lua_filters` in `pandoc_options()` to pass the Lua filter paths to use with a format. This allow output format authors to add filters for a custom format using the `pandoc` argument of `output_format()` and to get filters from a format using `fmt$pandoc$lua_filters`.
+    - The Lua filters of an output format are now passed to Pandoc in `render()`. By default, they are passed to Pandoc before any other format-defined or user-defined Pandoc arguments (usually via the `pandoc_args` option of an output format). This ensures that filters of an output format are executed first. To change the default, you need to deal with it in a custom format (i.e., modify the elements in `fmt$pandoc$lua_filters`, such as reordering them).
+
 - Since **rmarkdown** 1.16, Pandoc's fenced `Div`'s are converted to LaTeX environments when the output format is LaTeX, e.g., `::: {.center data-latex=""}` is converted to `\begin{center}`. The attribute `data-latex` of the `Div` was mandatory, even if it is empty. In **rmarkdown** 2.2, we silently drop this requirement, which means `::: {.center}` is converted to `\begin{center}`. This turns out to be a bad idea, because users have no control over which Div's to be converted to LaTeX environments. Previously, they could opt-in by the `data-latex` attribute, but with **rmarkdown** 2.3, all Div's are converted to LaTeX environments unconditionally. What's more, this change led to bugs like https://stackoverflow.com/q/62340425/559676 and https://github.com/rstudio/bookdown/issues/883. Therefore the `data-latex` attribute became mandatory again in this version. If the LaTeX environment does not need arguments, you may use `data-latex=""`.
 
 - The two Lua fitlers `pagebreak.lua` and `latex-div.lua` (introduced in **rmarkdown** 1.16) are also applied to the output format `beamer_presentation` now (thanks, @XiangyunHuang, #1815).
@@ -9,7 +14,6 @@ rmarkdown 2.4
 
 - Added the `number_sections` argument to following formats: `github_document`, `ioslides_presentation`, `md_document`, `odt_document`, `powerpoint_presentation`, `rtf_document`, `slidy_presentation`, `word_document`. These are powered by a lua filter and requires Pandoc > 2.0. It will silently have no effect has before with previous pandoc version (thanks @atusy 1893).  Pandoc >= 2.10.1 adds `--number-sections` for docx format, and thus `word_document` prefers the native feature to the lua filter (thanks, @jooyoungseo, #1869).
 
-
 - For the output format `pdf_document`, the option `fig_crop` will not be enabled unless both the programs `pdfcrop` and `ghostscript` are found (thanks, @dalupus, yihui/knitr#954).
 
 

R/beamer_presentation.R

@@ -126,8 +126,6 @@ beamer_presentation <- function(toc = FALSE,
   # make sure the graphics package is always loaded
   if (identical(template, "default")) args <- c(args, "--variable", "graphics=yes")
 
-  args <- c(args, pandoc_lua_filters(c("pagebreak.lua", "latex-div.lua")))
-
   # custom args
   args <- c(args, pandoc_args)
 
@@ -151,11 +149,14 @@ beamer_presentation <- function(toc = FALSE,
   # return format
   output_format(
     knitr = knitr_options_pdf(fig_width, fig_height, fig_crop, dev),
-    pandoc = pandoc_options(to = "beamer",
-                            from = from_rmarkdown(fig_caption, md_extensions),
-                            args = args,
-                            latex_engine = latex_engine,
-                            keep_tex = keep_tex),
+    pandoc = pandoc_options(
+      to = "beamer",
+      from = from_rmarkdown(fig_caption, md_extensions),
+      args = args,
+      latex_engine = latex_engine,
+      keep_tex = keep_tex,
+      lua_filters = pkg_file_lua(c("pagebreak.lua", "latex-div.lua"))
+    ),
     pre_processor = pre_processor,
     intermediates_generator = intermediates_generator,
     clean_supporting = !keep_tex,

R/context_document.R

@@ -90,9 +90,6 @@ context_document <- function(toc = FALSE,
   # content includes
   args <- c(args, includes_to_pandoc_args(includes))
 
-  # lua filters (added if pandoc > 2)
-  args <- c(args, pandoc_lua_filters("pagebreak.lua"))
-
   # args args
   args <- c(args, pandoc_args)
 
@@ -129,11 +126,13 @@ context_document <- function(toc = FALSE,
   # return format
   output_format(
     knitr = knitr_options_pdf(fig_width, fig_height, fig_crop, dev),
-    pandoc = pandoc_options(to = paste(c("context", output_extensions), collapse = ""),
-                            from = from_rmarkdown(fig_caption, md_extensions),
-                            args = args,
-                            keep_tex = FALSE,
-                            ext = ext),
+    pandoc = pandoc_options(
+      to = paste(c("context", output_extensions), collapse = ""),
+      from = from_rmarkdown(fig_caption, md_extensions),
+      args = args,
+      keep_tex = FALSE,
+      ext = ext,
+      lua_filters = pkg_file_lua("pagebreak.lua")),
     clean_supporting = !isTRUE(keep_tex),
     keep_md = keep_md,
     df_print = df_print,

R/github_document.R

@@ -33,9 +33,8 @@ github_document <- function(toc = FALSE,
   # add special markdown rendering template to ensure we include the title fields
   # and add an optional feature to number sections
   pandoc_args <- c(
-    pandoc_args, "--template", pkg_file_arg(
-      "rmarkdown/templates/github_document/resources/default.md"),
-    if (number_sections) pandoc_lua_filters("number-sections.lua")
+    pandoc_args, "--template",
+    pkg_file_arg("rmarkdown/templates/github_document/resources/default.md")
   )
 
 
@@ -46,8 +45,9 @@ github_document <- function(toc = FALSE,
 
   format <- md_document(
     variant = variant, toc = toc, toc_depth = toc_depth,
-    fig_width = fig_width, fig_height = fig_height, dev = dev,
-    df_print = df_print, includes = includes, md_extensions = md_extensions,
+    number_sections = number_sections, fig_width = fig_width,
+    fig_height = fig_height, dev = dev, df_print = df_print,
+    includes = includes, md_extensions = md_extensions,
     pandoc_args = pandoc_args
   )
 

R/html_document_base.R

@@ -106,9 +106,6 @@ html_document_base <- function(theme = NULL,
 
     preserved_chunks <<- extract_preserve_chunks(input_file)
 
-    # a lua filters added if pandoc2.0
-    args <- c(args, pandoc_lua_filters(c("pagebreak.lua", "latex-div.lua")))
-
     args
   }
 
@@ -170,7 +167,9 @@ html_document_base <- function(theme = NULL,
 
   output_format(
     knitr = NULL,
-    pandoc = pandoc_options(to = "html", from = NULL, args = args),
+    pandoc = pandoc_options(
+      to = "html", from = NULL, args = args,
+      lua_filters = pkg_file_lua(c("pagebreak.lua", "latex-div.lua"))),
     keep_md = FALSE,
     clean_supporting = FALSE,
     pre_knit = pre_knit,

R/ioslides_presentation.R

@@ -345,7 +345,8 @@ ioslides_presentation <- function(number_sections = FALSE,
     args <- c(args, pandoc_args)
 
     # number sections
-    if (number_sections) args <- c(args, pandoc_lua_filters("number-sections.lua"))
+    if (number_sections)
+      args <- c(args, pandoc_lua_filter_args(pkg_file_lua("number-sections.lua")))
 
     lua_writer <- file.path(dirname(input_file), "ioslides_presentation.lua")
     # The input directory may not be writable (on e.g. Shiny Server), so write

R/md_document.R

@@ -60,9 +60,6 @@ md_document <- function(variant = "markdown_strict",
   # pandoc args
   args <- c(args, pandoc_args)
 
-  # number sections with lua filter
-  if (number_sections) args <- c(args, pandoc_lua_filters("number-sections.lua"))
-
   # add post_processor for yaml preservation
   post_processor <- if (preserve_yaml && variant != 'markdown') {
     function(metadata, input_file, output_file, clean, verbose) {
@@ -79,10 +76,12 @@ md_document <- function(variant = "markdown_strict",
   # return format
   output_format(
     knitr = knitr_options_html(fig_width, fig_height, fig_retina, FALSE, dev),
-    pandoc = pandoc_options(to = variant,
-                            from = from_rmarkdown(extensions = md_extensions),
-                            args = args,
-                            ext = ext),
+    pandoc = pandoc_options(
+      to = variant,
+      from = from_rmarkdown(extensions = md_extensions),
+      args = args,
+      ext = ext,
+      lua_filters = if (number_sections) pkg_file_lua("number-sections.lua")),
     clean_supporting = FALSE,
     df_print = df_print,
     post_processor = post_processor

R/odt_document.R

@@ -63,15 +63,9 @@ odt_document <- function(number_sections = FALSE,
   # reference odt
   args <- c(args, reference_doc_args("odt", reference_odt))
 
-  # lua filters (added if pandoc > 2)
-  args <- c(args, pandoc_lua_filters("pagebreak.lua"))
-
   # pandoc args
   args <- c(args, pandoc_args)
 
-  # number sections with lua filter
-  if (number_sections) args <- c(args, pandoc_lua_filters("number-sections.lua"))
-
   saved_files_dir <- NULL
   pre_processor <- function(metadata, input_file, runtime, knit_meta, files_dir, output_dir) {
     saved_files_dir <<- files_dir
@@ -85,9 +79,12 @@ odt_document <- function(number_sections = FALSE,
   # return output format
   output_format(
     knitr = knitr,
-    pandoc = pandoc_options(to = "odt",
-                            from = from_rmarkdown(fig_caption, md_extensions),
-                            args = args),
+    pandoc = pandoc_options(
+      to = "odt",
+      from = from_rmarkdown(fig_caption, md_extensions),
+      args = args,
+      lua_filters = pkg_file_lua(c(
+        "pagebreak.lua", if (number_sections) "number-sections.lua"))),
     keep_md = keep_md,
     pre_processor = pre_processor,
     intermediates_generator = intermediates_generator

R/output_format.R

@@ -198,6 +198,7 @@ merge_pandoc_options <- function(base,
 
   res <- merge_lists(base, overlay, recursive = FALSE)
   res$args <- c(base$args, overlay$args)
+  res$lua_filters <- c(base$lua_filters, overlay$lua_filters)
   res
 }
 
@@ -290,6 +291,10 @@ knitr_options_pdf <- function(fig_width,
 #'   chooses default based on \code{to}). This is typically used to force
 #'   the final output of a latex or beamer conversion to be \code{.tex}
 #'   rather than \code{.pdf}.
+#' @param lua_filters  Character vector of file paths to lua filters to use with
+#'   this format. They will be added to pandoc command line call using
+#'   \code{--lua-filter} argument. See \code{vignette("lua-filters", package =
+#'   "rmarkdown")} to know more about lua filters.
 #' @return An list that can be passed as the \code{pandoc} argument of the
 #'   \code{\link{output_format}} function.
 #' @seealso \link{output_format}, \link{rmarkdown_format}
@@ -299,13 +304,15 @@ pandoc_options <- function(to,
                            args = NULL,
                            keep_tex = FALSE,
                            latex_engine = c("pdflatex", "lualatex", "xelatex"),
-                           ext = NULL) {
+                           ext = NULL,
+                           lua_filters = NULL) {
   list(to = to,
        from = from,
        args = args,
        keep_tex = keep_tex,
        latex_engine = match.arg(latex_engine),
-       ext = ext)
+       ext = ext,
+       lua_filters = lua_filters)
 }
 
 #' R Markdown input format definition