Add an option to opt-out using custom environment lua filter (rstudio…

…#1288)

Setting `options(bookdown.theorem.enabled  = FALSE)` will not include the Lua filter that is used to handle custom environment in **bookdown**

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: bookdown
 Type: Package
 Title: Authoring Books and Technical Documents with R Markdown
-Version: 0.24.3
+Version: 0.24.4
 Authors@R: c(
     person("Yihui", "Xie", role = c("aut", "cre"), email = "[email protected]", comment = c(ORCID = "0000-0003-0645-5666")),
     person("JJ", "Allaire", role = "ctb"),

NEWS.md

@@ -1,5 +1,9 @@
 # CHANGES IN bookdown VERSION 0.25
 
+## NEW FEATURES
+
+- Set option `bookdown.theorem.enabled = FALSE` to opt-out **bookdown** special Theorem and Proof environment syntax. `options(bookdown.theorem.enabled = FALSE)` must be called before the function to render the book, e.g in a project's `.Rprofile`. This can be useful for advanced users who only want PDF output and needs to handle themselves the environment using LaTeX directly, or [Custom Blocks](https://bookdown.org/yihui/rmarkdown-cookbook/custom-blocks.html) syntax without **bookdown** interfering (thanks, @finkelshtein, #1285).
+
 ## BUG FIXES
 
 - Fix an issue with Pandoc 2.15 and footnote relocation in each chapter (#1275).

R/utils.R

@@ -32,10 +32,13 @@ common_format_config = function(
   # provide file_scope if requested
   if (file_scope) config$file_scope = md_chapter_splitter
 
-  # prepend the custom-environment filter
-  config$pandoc$lua_filters = c(
-    lua_filter("custom-environment.lua"), config$pandoc$lua_filters
-  )
+  # prepend the custom-environment filter unless opt-out
+  if (getOption("bookdown.theorem.enabled", TRUE)) {
+    config$pandoc$lua_filters = c(
+      lua_filter("custom-environment.lua"),
+      config$pandoc$lua_filters
+    )
+  }
   # and add bookdown metadata file for the filter to work
   config$pandoc$args = c(bookdown_yml_arg(), config$pandoc$args)