chapter_numbering yaml option: turn numbering off or start at a value
The automatic chapter numbering can now be controlled from the yaml
header. The default TRUE numbers the # chapters from 1 as before.
chapter_numbering: false turns the numbering off -- headings keep
exactly what was typed, including manually typed numbers, and the
overview TOC shows the titles as typed (the numbering script is not
emitted at all). A number starts the enumeration at that value, e.g.
chapter_numbering: 5 for a continuation deck; references, appendix and
thank-you chapters stay excluded and uncounted in every mode.
Change-Id: I69af1414aedd14c9be09650c78b3219bf63c4d1a
diff --git a/NEWS.md b/NEWS.md
index a5e648e..0cc4a7a 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,5 +1,7 @@
# revealjs.ids (development version)
+- New `chapter_numbering` yaml option controlling the automatic chapter numbering: `false` turns it off (headings keep exactly what was typed, including manually typed numbers), a number starts the enumeration at that value (e.g. `chapter_numbering: 5` for a continuation deck). The default `TRUE` numbers from 1 as before.
+
- Adaptive vertical centering of slide content: slides with little content now center their body content in the space between the heading and the footer instead of sitting glued below the title bar; packed slides still start directly below the heading and overflow downwards exactly as before, and centered content never covers the footer. Reveal.js' own `center` option could not be used (it also vertically centers the headings); instead each slide's body content is grouped into a wrapper whose auto margins do the centering, so no measuring and no resize handling is involved. Heading-only section-divider slides keep their dedicated centered-title layout.
# revealjs.ids 0.9.1.9010
diff --git a/R/revealjs_presentation.R b/R/revealjs_presentation.R
index d93e617..31c14f1 100644
--- a/R/revealjs_presentation.R
+++ b/R/revealjs_presentation.R
@@ -124,7 +124,9 @@
#' the overview slide's table of contents uses them as its ordered list's
#' enumeration. Decks rendered with `slide_level = 1` (one `#` heading per
#' slide) are left unnumbered -- there, headings denote slides, not
-#' chapters.
+#' chapters. The numbering can be turned off with `chapter_numbering: false`
+#' in the yaml header, or started at another number with e.g.
+#' `chapter_numbering: 5` (useful for continuation decks).
#'
#' ## Overview slides
#'
@@ -225,6 +227,13 @@
#' 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 chapter_numbering `TRUE` (the default) numbers the `#` chapter
+#' headings automatically ("1. Introduction", "2. Methods", ...), skipping
+#' references, appendix and thank-you chapters. `FALSE` turns the numbering
+#' off -- headings keep exactly what was typed, including any manually
+#' typed numbers. A number starts the enumeration at that value:
+#' `chapter_numbering = 5` numbers the first chapter "5." (useful for
+#' continuation decks).
#' @param theme Visual theme. The dedicated IDS corporate design theme
#' ("ids") is the default and the only supported theme.
#' @param transition Slide transition (
@@ -278,6 +287,7 @@
revealjs_presentation <- function(incremental = FALSE,
center = FALSE,
slide_level = 2,
+ chapter_numbering = TRUE,
toc = FALSE,
toc_depth = 3,
fig_width = 8,
@@ -326,6 +336,21 @@
# slide level
args <- c(args, "--slide-level", as.character(slide_level))
+ # chapter numbering: FALSE disables the automatic "1. ", "2. " prefixes on
+ # chapter headings; a number starts the enumeration at that value (useful
+ # e.g. for continuation decks). TRUE, the default, numbers from 1.
+ if (identical(chapter_numbering, FALSE)) {
+ args <- c(args, pandoc_variable_arg("chapter-numbering-off"))
+ } else if (is.numeric(chapter_numbering)) {
+ if (chapter_numbering != 1) {
+ args <- c(args, pandoc_variable_arg(
+ "chapter-numbering-start", as.integer(chapter_numbering)
+ ))
+ }
+ } else if (!isTRUE(chapter_numbering)) {
+ stop("chapter_numbering must be TRUE, FALSE or a number", call. = FALSE)
+ }
+
# theme
theme <- match.arg(theme, revealjs_themes())
if (identical(theme, "default")) {
diff --git a/README.Rmd b/README.Rmd
index 9418dbd..aecb0a8 100644
--- a/README.Rmd
+++ b/README.Rmd
@@ -182,6 +182,22 @@
Decks with `slide_level: 1` (one `#` heading per slide) are left unnumbered -- there, headings denote slides, not chapters.
+The numbering can be turned off with the `chapter_numbering` option -- headings then keep exactly what was typed:
+
+``` yaml
+output:
+ revealjs.ids::revealjs_presentation:
+ chapter_numbering: false
+```
+
+A number starts the enumeration at that value instead, which is useful for continuation decks:
+
+``` yaml
+output:
+ revealjs.ids::revealjs_presentation:
+ chapter_numbering: 5
+```
+
## Vertical Content Centering
Slides with little content no longer sit glued below the title bar: whenever there is free space, the slide's body content is centered in the area between the heading and the footer. Slides that are too packed start directly below the heading and overflow downwards exactly as before, and centered content never covers the footer. Reveal.js' own `center` option could not be used for this, because it also vertically centers the headings. Heading-only section-divider slides keep their dedicated centered-title layout.
diff --git a/README.md b/README.md
index e842f65..4a762d5 100644
--- a/README.md
+++ b/README.md
@@ -263,6 +263,24 @@
Decks with `slide_level: 1` (one `#` heading per slide) are left
unnumbered -- there, headings denote slides, not chapters.
+The numbering can be turned off with the `chapter_numbering` option --
+headings then keep exactly what was typed:
+
+``` yaml
+output:
+ revealjs.ids::revealjs_presentation:
+ chapter_numbering: false
+```
+
+A number starts the enumeration at that value instead, which is useful
+for continuation decks:
+
+``` yaml
+output:
+ revealjs.ids::revealjs_presentation:
+ chapter_numbering: 5
+```
+
## Vertical Content Centering
Slides with little content no longer sit glued below the title bar:
diff --git a/inst/rmarkdown/templates/revealjs_presentation/resources/default.html b/inst/rmarkdown/templates/revealjs_presentation/resources/default.html
index f5eb25b..287082e 100644
--- a/inst/rmarkdown/templates/revealjs_presentation/resources/default.html
+++ b/inst/rmarkdown/templates/revealjs_presentation/resources/default.html
@@ -1045,17 +1045,22 @@
};
})();
</script>
+$if(chapter-numbering-off)$
+$else$
<script>
// Automatic chapter numbering (ported from the gdoc2reveal workflow):
// chapter headings get a sequential "1. ", "2. " ... prefix, except
// references, appendix and thank-you chapters, which keep their bare
// titles and are not counted. Manually typed leading numbers are stripped
// first, so rendering twice or renumbering an already numbered deck stays
- // stable. Runs before the overview TOC builder below: the menu plugin and
- // the transcript view show the numbers, while the overview TOC strips
- // them again and numbers its ordered list entries instead, like the old
- // Google Docs workflow did.
+ // stable. Decks can turn the numbering off (chapter_numbering: false) or
+ // start it at another number (chapter_numbering: 5, e.g. for a
+ // continuation deck) via the yaml option. Runs before the overview TOC
+ // builder below: the menu plugin and the transcript view show the
+ // numbers, while the overview TOC strips them again and numbers its
+ // ordered list entries instead, like the old Google Docs workflow did.
(function () {
+ var start = $if(chapter-numbering-start)$$chapter-numbering-start$$else$1$endif$;
function firstTextNode(el) {
var n = el.firstChild;
while (n && n.nodeType !== Node.TEXT_NODE) n = n.nextSibling;
@@ -1064,7 +1069,7 @@
function numberChapters() {
if (typeof Reveal === 'undefined' || !Reveal.isReady()) return;
- var n = 0;
+ var n = start - 1;
Reveal.getSlides().forEach(function (slide) {
if (!window.idsChapters.isChapterSlide(slide)) return;
var h = slide.querySelector('h1');
@@ -1094,6 +1099,7 @@
}
})();
</script>
+$endif$
<script>
// Slides whose (only) heading is "Overview" or "Überblick" are
// automatically populated with a table of contents of the deck's h1 slide
diff --git a/man/revealjs_presentation.Rd b/man/revealjs_presentation.Rd
index 2741765..c006418 100644
--- a/man/revealjs_presentation.Rd
+++ b/man/revealjs_presentation.Rd
@@ -8,6 +8,7 @@
incremental = FALSE,
center = FALSE,
slide_level = 2,
+ chapter_numbering = TRUE,
toc = FALSE,
toc_depth = 3,
fig_width = 8,
@@ -49,6 +50,14 @@
building vertically. It is not recommended that you use deeper nesting of
section levels with reveal.js.}
+\item{chapter_numbering}{\code{TRUE} (the default) numbers the \verb{#} chapter
+headings automatically ("1. Introduction", "2. Methods", ...), skipping
+references, appendix and thank-you chapters. \code{FALSE} turns the numbering
+off -- headings keep exactly what was typed, including any manually
+typed numbers. A number starts the enumeration at that value:
+\code{chapter_numbering = 5} numbers the first chapter "5." (useful for
+continuation decks).}
+
\item{toc}{\code{TRUE} to include a table of contents in the output (only
level 1 headers will be included in the table of contents).}
@@ -280,7 +289,9 @@
the overview slide's table of contents uses them as its ordered list's
enumeration. Decks rendered with \code{slide_level = 1} (one \verb{#} heading per
slide) are left unnumbered -- there, headings denote slides, not
-chapters.
+chapters. The numbering can be turned off with \code{chapter_numbering: false}
+in the yaml header, or started at another number with e.g.
+\code{chapter_numbering: 5} (useful for continuation decks).
}
\subsection{Overview slides}{
diff --git a/tests/testthat/test-revealjs_presentation.R b/tests/testthat/test-revealjs_presentation.R
index ade1c9a..85ad022 100644
--- a/tests/testthat/test-revealjs_presentation.R
+++ b/tests/testthat/test-revealjs_presentation.R
@@ -18,3 +18,45 @@
"TOC"
)
})
+
+test_that("chapter_numbering option controls the numbering script", {
+ skip_if_not_pandoc()
+ rmd <- local_temp_rmd_file(
+ "---",
+ "title: 'Chapter numbering test'",
+ "output: revealjs.ids::revealjs_presentation",
+ "---",
+ "",
+ "# One",
+ "",
+ "## a",
+ "",
+ "# Two"
+ )
+ on <- paste(.render_and_read(rmd, xml = FALSE), collapse = "\n")
+ expect_match(on, "function numberChapters", fixed = TRUE)
+ expect_match(on, "var start = 1;", fixed = TRUE)
+
+ off <- paste(.render_and_read(
+ rmd,
+ output_options = list(chapter_numbering = FALSE),
+ xml = FALSE
+ ), collapse = "\n")
+ expect_no_match(off, "function numberChapters", fixed = TRUE)
+
+ started <- paste(.render_and_read(
+ rmd,
+ output_options = list(chapter_numbering = 5),
+ xml = FALSE
+ ), collapse = "\n")
+ expect_match(started, "var start = 5;", fixed = TRUE)
+
+ expect_error(
+ .render_and_read(
+ rmd,
+ output_options = list(chapter_numbering = "yes"),
+ xml = FALSE
+ ),
+ "chapter_numbering"
+ )
+})