diff --git a/R/revealjs_presentation.R b/R/revealjs_presentation.R
index de0e37b..84614ae 100644
--- a/R/revealjs_presentation.R
+++ b/R/revealjs_presentation.R
@@ -1,7 +1,83 @@
 #' Convert to a reveal.js presentation
 #'
 #' Format for converting from R Markdown to a reveal.js presentation.
+#' 
+#' In reveal.js presentations you can use level 1 or level 2 headers for slides.
+#' If you use a mix of level 1 and level 2 headers then a two-dimensional layout
+#' will be produced, with level 1 headers building horizontally and level 2
+#' headers building vertically.
 #'
+#' For additional documentation on using revealjs presentations see
+#' <https://github.com/rstudio/revealjs>
+#' 
+#' # About plugins
+#' 
+#' ## Built-in plugins with reveal.js
+#' 
+#' ### Zoom 
+#' 
+#' When activated, ALT + Click can be used to zoom on a slide.
+#' 
+#' ### Notes 
+#'  
+#' Show a [speaker view](https://revealjs.com/speaker-view/) in a separated
+#' window. This speaker view contains a timer, current slide, next slide, and
+#' speaker notes. It also duplicate the window to have presentation mode
+#' synchronized with main presentation.
+#' 
+#' Use 
+#' ```markdown
+#' ::: notes
+#' Content of speaker notes
+#' :::
+#' ```
+#' to create notes only viewable in presentation mode.
+#' 
+#' ### Search
+#' 
+#' When opt-in, it is possible to show a search box when pressing `CTRL + SHIFT +
+#' F`. It will seach in the whole presentation, and highlight matched words. The
+#' matches will also be highlighted in overview mode (pressing ESC to see all
+#' slides in one scrollable view)
+#' 
+#' ## Menu 
+#' 
+#' A slideout menu plugin for Reveal.js to quickly jump to any slide by title.
+#' 
+#' Version `r version <- readLines(revealjs_lib_path("plugin", "menu", "VERSION"))` is
+#' currently used and documentation for configurations can be found at
+#' [denehyg/reveal.js-menu](https://github.com/denehyg/reveal.js-menu/blob/`r version`/README.md)
+#' 
+#' ### Known limitations
+#' 
+#' Some configurations cannot be modified in the current template: 
+#' 
+#' * `loadIcons: false`  the fontawesome icons are loaded by \pkg{rmarkdown}
+#' when this plugin is used
+#' * `custom: false`
+#' * `themes: false`
+#' * `transitions: false`
+
+#' ## Chalkboard 
+#' 
+#' A plugin adding a chalkboard and slide annotation
+#' 
+#' Version `r version <- readLines(revealjs_lib_path("plugin", "chalkboard", "VERSION"))` is
+#' currently used and documentation for configurations can be found at
+#' [rajgoel/reveal.js-plugins](https://github.com/rajgoel/reveal.js-plugins/tree/`r version`/4.1.5/chalkboard)
+#' 
+#' By default, chalkboard and annotations modes will be accessible using keyboard
+#' shortcuts, respectively, pressing B, or pressing C.  
+#' In addition, buttons on the bottom left can be added by using the following 
+#' 
+#' ```yaml
+#' reveal_plugins: 
+#'   - chalkboard
+#' reveal_options:
+#'   chalkboard:
+#'     toggleNotesButton: true
+#'     toggleChalkboardButton: true
+#' ```
 #' @inheritParams rmarkdown::beamer_presentation
 #' @inheritParams rmarkdown::pdf_document
 #' @inheritParams rmarkdown::html_document
@@ -12,15 +88,17 @@
 #'   produced, with level 1 headers building horizontally and level 2 headers
 #'   building vertically. It is not recommended that you use deeper nesting of
 #'   section levels with reveal.js.
-#' @param theme Visual theme ("simple", "sky", "beige", "serif", "solarized",
-#'   "blood", "moon", "night", "black", "league" or "white").
-#' @param transition Slide transition ("default", "none", "fade", "slide",
-#'   "convex", "concave" or "zoom")
-#' @param background_transition Slide background-transition ("default", "none",
-#'   "fade", "slide", "convex", "concave" or "zoom")
+#' @param theme Visual theme (`r knitr::combine_words(setdiff(revealjs_themes(), "default"), before = '"', and = " or ")`)
+#' @param transition Slide transition (
+#' `r (trans <- knitr::combine_words(setdiff(revealjs_transitions(), "default"), before = '"', and = " or "))`
+#' )
+#' @param background_transition Slide background-transition (
+#' `r trans`
+#' )
 #' @param reveal_options Additional options to specify for reveal.js (see
-#'   <https://revealjs.com/config/>
-#'    for details).
+#'   <https://revealjs.com/config/> for details). Options for plugins can also
+#'   be passed, using plugin name as first level key (e.g `list(slideNumber =
+#'   FALSE, menu = list(number = TRUE))`).
 #' @param reveal_plugins Reveal plugins to include. Available plugins include
 #'   "notes", "search", "zoom", "chalkboard", and "menu". Note that
 #'   `self_contained` must be set to `FALSE` in order to use Reveal
@@ -37,16 +115,6 @@
 #'
 #' @return R Markdown output format to pass to [rmarkdown::render()]
 #'
-#' @details
-#'
-#' In reveal.js presentations you can use level 1 or level 2 headers for slides.
-#' If you use a mix of level 1 and level 2 headers then a two-dimensional layout
-#' will be produced, with level 1 headers building horizontally and level 2
-#' headers building vertically.
-#'
-#' For additional documentation on using revealjs presentations see
-#' <https://github.com/rstudio/revealjs>
-#'
 #' @examples
 #' \dontrun{
 #'
@@ -72,8 +140,8 @@
                                   fig_caption = FALSE,
                                   self_contained = TRUE,
                                   theme = "simple",
-                                  transition = "default",
-                                  background_transition = "default",
+                                  transition = "convex",
+                                  background_transition = "fade",
                                   reveal_options = NULL,
                                   reveal_plugins = NULL,
                                   highlight = "default",
@@ -126,10 +194,18 @@
 
   # transition
   transition <- match.arg(transition, revealjs_transitions())
+  if (identical(transition, "default")) {
+    # revealjs default is convex
+    transition <- "convex"
+  }
   args <- c(args, pandoc_variable_arg("transition", transition))
 
   # background_transition
   background_transition <- match.arg(background_transition, revealjs_transitions())
+  if (identical(background_transition, "default")) {
+    # revealjs default is fade
+    background_transition <- "fade"
+  }
   args <- c(args, pandoc_variable_arg("backgroundTransition", background_transition))
 
   # use history
@@ -175,9 +251,13 @@
     }
 
     # add plugins
+    if ("chalkboard" %in% reveal_plugins) {
+      # chalkboard require customcontrols so we add it to activate in the template
+      reveal_plugins <- c(reveal_plugins, "customcontrols")
+    }
     sapply(reveal_plugins, function(plugin) {
-      args <<- c(args, pandoc_variable_arg(paste0("plugin-", plugin), "1"))
-      if (plugin %in% c("chalkboard", "menu")) {
+      args <<- c(args, pandoc_variable_arg(paste0("plugin-", plugin)))
+      if (plugin %in% c("customcontrols", "menu")) {
         extra_dependencies <<- append(
           extra_dependencies,
           list(rmarkdown::html_dependency_font_awesome())
@@ -215,7 +295,7 @@
     args <- c()
 
     # reveal.js
-    revealjs_path <- system.file("reveal.js-3.3.0.1", package = "revealjs")
+    revealjs_path <- revealjs_lib_path()
     if (!self_contained || identical(.Platform$OS.type, "windows")) {
       revealjs_path <- relative_to(
         output_dir, render_supporting_files(revealjs_path, lib_dir)
@@ -256,9 +336,10 @@
 
 revealjs_themes <- function() {
   c(
-    "default",
-    "dark",
+    "default", # not used by reveal
     "simple",
+    "dark", # our alias for black
+    "black",
     "sky",
     "beige",
     "serif",
@@ -266,21 +347,19 @@
     "blood",
     "moon",
     "night",
-    "black",
     "league",
     "white"
   )
 }
 
-
 revealjs_transitions <- function() {
   c(
-    "default",
-    "none",
+    "default", # not used by reveal
+    "convex",
     "fade",
     "slide",
-    "convex",
     "concave",
-    "zoom"
+    "zoom",
+    "none"
   )
 }
diff --git a/R/utils.R b/R/utils.R
index 7251cff..10cd223 100644
--- a/R/utils.R
+++ b/R/utils.R
@@ -5,6 +5,17 @@
               package = "revealjs")
 }
 
+
+revealjs_lib_path <- function(...) {
+  pkg <- system.file(package = "revealjs")
+  lib_folder <- list.files(pkg, pattern = "reveal.js-")[1]
+  system.file(lib_folder, ..., package = "revealjs")
+}
+
+revealjs_version <- function() {
+  as.numeric_version(gsub(".*reveal\\.js-(.*)$", "\\1", revealjs_lib_path()))
+}
+
 # Convert boolean from R to JS boolean
 jsbool <- function(value) ifelse(value, "true", "false")
 
@@ -13,10 +24,17 @@
   if (is.logical(value)) {
     value <- jsbool(value)
   } else if (is.character(value)) {
-    # Special handling for some chalkboard plugin options
-    # e.g: color: [ 'rgba(0,0,255,1)', 'rgba(255,255,255,0.5)' ]
-    if (grepl("chalkboard-(background|color|draw|pen)", option)) {
-      value <- sprintf("[%s]", paste(paste0("'", value, "'"), collapse = ", "))
+    # Special handling for some vector options 
+    if (
+      # chalkboard plugin options
+      # e.g: color: [ 'rgba(0,0,255,1)', 'rgba(255,255,255,0.5)' ]
+      grepl("chalkboard-(background|draw)", option)
+      # e.g autoAnimateStyles: ['opacity','color']
+      || grepl("autoAnimateStyles", option)
+    ) {
+      if (length(value) > 1 || !grepl("^\\[.*\\]$", value)) {
+        value <- sprintf("[%s]", paste(paste0("'", value, "'"), collapse = ", "))
+      }
     }
     # Add quotes around some config that can be several type
     # like number or percent unit or slideNumber = true or slideNumber = 'c/t'