diff --git a/DESCRIPTION b/DESCRIPTION index 2118f78..a36de64 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,12 +1,13 @@ Package: deckroadmap Title: Roadmap Footers for 'Reveal.js' Slides in 'Quarto' and 'R Markdown' -Version: 0.1.4.9000 +Version: 0.1.5.9000 Authors@R: person("Tiger", "Tang", email = "tigerloveslobsters@gmail.com", role = c("aut", "cre")) Description: Adds section-aware roadmap footers to 'Reveal.js' slide decks created with 'Quarto' or 'R Markdown'. The footer highlights completed, current, and upcoming sections as slides advance. Supports multiple - visual styles with configurable colors, size, and positioning options. + visual styles, inherited section tags, roadmap-free slides, and + configurable colors, size, and positioning options. License: MIT + file LICENSE Encoding: UTF-8 Roxygen: list(markdown = TRUE) diff --git a/NEWS.md b/NEWS.md index 91e292d..0b6fb0d 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,12 @@ # deckroadmap news +## deckroadmap 0.1.5.9000 + +- Added support for inherited `data-roadmap` tags so untagged slides can inherit the most recent section by default. +- Added support for `data-roadmap="none"` to hide the roadmap on a specific slide. +- Updated README, examples, and vignette to reflect the new slide-tagging behavior. +- Improved documentation around section tagging and roadmap-free slides. + # deckroadmap 0.1.4 - Initial CRAN release. diff --git a/R/use_roadmap.R b/R/use_roadmap.R index 7f8b98e..e0a9558 100644 --- a/R/use_roadmap.R +++ b/R/use_roadmap.R @@ -14,6 +14,9 @@ #' progress style. #' @param todo_bg_color CSS background color for upcoming sections in #' progress style. +#' @param inherit_tags Logical; if `TRUE`, untagged slides inherit the most +#' recent `data-roadmap` value. Use `data-roadmap="none"` on a slide to hide +#' the roadmap entirely for that slide. #' #' @return An HTML tag with attached dependencies. #' @@ -49,9 +52,11 @@ use_roadmap <- function( todo_color = NULL, active_bg_color = NULL, done_bg_color = NULL, - todo_bg_color = NULL + todo_bg_color = NULL, + inherit_tags = TRUE ) { stopifnot(is.character(sections), length(sections) >= 2) + stopifnot(is.logical(inherit_tags), length(inherit_tags) == 1, !is.na(inherit_tags)) style <- match.arg(style) @@ -59,6 +64,7 @@ use_roadmap <- function( id = id, `data-sections` = paste(sections, collapse = "|"), `data-style` = style, + `data-inherit-tags` = tolower(as.character(inherit_tags)), style = paste0( "display:none;", "--deckroadmap-font-size:", font_size, ";", diff --git a/README.Rmd b/README.Rmd index 6ba1f5a..e2b22ed 100644 --- a/README.Rmd +++ b/README.Rmd @@ -15,6 +15,7 @@ It helps audiences see what has been covered, what section they are currently in ![](man/figures/preview-all.png) Read the background story and design notes in the [blog post](https://tigertang.org/deckroadmap/). +Documentation: [codingtigertang.github.io/deckroadmap](https://codingtigertang.github.io/deckroadmap/) ## Installation @@ -37,24 +38,26 @@ Many business, teaching, and conference presentations use a roadmap bar to help With one function call, you can add a persistent footer that marks: - completed sections - - the current section - - upcoming sections +## Why not just use the Reveal.js progress bar? + +The built-in Reveal.js progress bar shows how far you are through the slide deck. +`deckroadmap` answers a different question: where are you in the structure of the talk? + ## Supported formats `deckroadmap` currently supports: - Quarto Revealjs presentations - - R Markdown Revealjs presentations It is designed for Reveal.js-based HTML slides. ## Basic usage -Add `use_roadmap()` near the top of your document, then tag each slide with a section name using data-roadmap. +Add `use_roadmap()` near the top of your document, then tag slides with `data-roadmap` section names. Untagged slides inherit the most recent section by default. ```{r eval=FALSE} library(deckroadmap) @@ -78,13 +81,36 @@ Then use matching section labels on your slides, for example: ## Next steps {data-roadmap="Next Steps"} ``` +## Inheriting section tags + +By default, untagged slides inherit the most recent `data-roadmap` value. This makes it easier to tag only the first slide of each section. + +``` markdown +## Intro {data-roadmap="Intro"} + +## More intro content + +## Problem {data-roadmap="Problem"} + +## More problem detail +``` +In this example, the second slide inherits Intro, and the fourth slide inherits Problem. + +## Roadmap-free slides + +To hide the roadmap on a specific slide, use: + +``` markdown +## Break slide {data-roadmap="none"} +``` +This is useful for title slides, divider slides, or transitions where you do not want the roadmap to appear. ## Full examples Full working examples are included in the `examples/` folder: -- `examples/quarto-demo.qmd` -- `examples/rmarkdown-demo.Rmd` +- [Quarto demo](examples/quarto-demo.qmd) +- [R Markdown demo](examples/rmarkdown-demo.Rmd) These show complete Reveal.js slide documents for Quarto and R Markdown. @@ -177,3 +203,11 @@ use_roadmap( ``` ![](man/figures/preview-text-styling2.png) + +## Notes + +* Section names in sections should match the `data-roadmap` values used on slides. +* Untagged slides inherit the most recent section by default. +* Use `data-roadmap="none"` to hide the roadmap on a specific slide. +* `deckroadmap` is designed for Reveal.js slide decks, not PowerPoint output. +* For best results, keep the section list short and readable. diff --git a/README.md b/README.md index 71235aa..0be2c66 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,8 @@ options for colors, size, and positioning. ![](man/figures/preview-all.png) Read the background story and design notes in the [blog post](https://tigertang.org/deckroadmap/). +Documentation: +[codingtigertang.github.io/deckroadmap](https://codingtigertang.github.io/deckroadmap/) ## Installation @@ -42,25 +44,29 @@ pattern to Reveal.js slides in a simple R-friendly way. With one function call, you can add a persistent footer that marks: - completed sections - - the current section - - upcoming sections +## Why not just use the Reveal.js progress bar? + +The built-in Reveal.js progress bar shows how far you are through the +slide deck. `deckroadmap` answers a different question: where are you in +the structure of the talk? + ## Supported formats `deckroadmap` currently supports: - Quarto Revealjs presentations - - R Markdown Revealjs presentations It is designed for Reveal.js-based HTML slides. ## Basic usage -Add `use_roadmap()` near the top of your document, then tag each slide -with a section name using data-roadmap. +Add `use_roadmap()` near the top of your document, then tag slides with +`data-roadmap` section names. Untagged slides inherit the most recent +section by default. ``` r library(deckroadmap) @@ -85,12 +91,41 @@ Then use matching section labels on your slides, for example: ## Next steps {data-roadmap="Next Steps"} ``` +## Inheriting section tags + +By default, untagged slides inherit the most recent `data-roadmap` +value. This makes it easier to tag only the first slide of each section. + +``` markdown +## Intro {data-roadmap="Intro"} + +## More intro content + +## Problem {data-roadmap="Problem"} + +## More problem detail +``` + +In this example, the second slide inherits Intro, and the fourth slide +inherits Problem. + +## Roadmap-free slides + +To hide the roadmap on a specific slide, use: + +``` markdown +## Break slide {data-roadmap="none"} +``` + +This is useful for title slides, divider slides, or transitions where +you do not want the roadmap to appear. + ## Full examples Full working examples are included in the `examples/` folder: -- `examples/quarto-demo.qmd` -- `examples/rmarkdown-demo.Rmd` +- [Quarto demo](examples/quarto-demo.qmd) +- [R Markdown demo](examples/rmarkdown-demo.Rmd) These show complete Reveal.js slide documents for Quarto and R Markdown. @@ -191,3 +226,13 @@ use_roadmap( ``` ![](man/figures/preview-text-styling2.png) + +## Notes + +- Section names in sections should match the `data-roadmap` values used + on slides. +- Untagged slides inherit the most recent section by default. +- Use `data-roadmap="none"` to hide the roadmap on a specific slide. +- `deckroadmap` is designed for Reveal.js slide decks, not PowerPoint + output. +- For best results, keep the section list short and readable. diff --git a/examples/quarto-demo.qmd b/examples/quarto-demo.qmd index 19d1b09..3767dd7 100644 --- a/examples/quarto-demo.qmd +++ b/examples/quarto-demo.qmd @@ -18,7 +18,7 @@ use_roadmap( This is the opening slide. -## Why this matters {data-roadmap="Intro"} +## Why this matters Some framing content. @@ -26,7 +26,7 @@ Some framing content. Describe the challenge here. -## What changed {data-roadmap="Problem"} +## What changed More problem context. @@ -34,7 +34,7 @@ More problem context. Start the analysis section. -## Key findings {data-roadmap="Analysis"} +## Key findings Show results here. @@ -50,6 +50,6 @@ Discuss caveats and decisions. End with the action plan. -## Q&A {data-roadmap="Next Steps"} +## Q&A {data-roadmap="none"} Questions. \ No newline at end of file diff --git a/examples/rmarkdown-demo.rmd b/examples/rmarkdown-demo.rmd index 25d5479..1713a5e 100644 --- a/examples/rmarkdown-demo.rmd +++ b/examples/rmarkdown-demo.rmd @@ -16,7 +16,7 @@ use_roadmap( This is the opening slide. -## Why this matters {data-roadmap="Intro"} +## Why this matters Some framing content. @@ -24,7 +24,7 @@ Some framing content. Describe the challenge here. -## What changed {data-roadmap="Problem"} +## What changed More problem context. @@ -32,7 +32,7 @@ More problem context. Start the analysis section. -## Key findings {data-roadmap="Analysis"} +## Key findings Show results here. @@ -40,7 +40,7 @@ Show results here. Explain the recommendation. -## Tradeoffs {data-roadmap="Recommendation"} +## Tradeoffs {data-roadmap="none"} Discuss caveats and decisions. @@ -48,6 +48,6 @@ Discuss caveats and decisions. End with the action plan. -## Q&A {data-roadmap="Next Steps"} +## Q&A {data-roadmap="none"} Questions. \ No newline at end of file diff --git a/inst/assets/roadmap.js b/inst/assets/roadmap.js index 4765ea9..568fecd 100644 --- a/inst/assets/roadmap.js +++ b/inst/assets/roadmap.js @@ -14,10 +14,15 @@ document.addEventListener("DOMContentLoaded", function () { function getStyleName() { const config = getConfig(); if (!config) return "pill"; - return config.getAttribute("data-style") || "pill"; } + function getInheritTags() { + const config = getConfig(); + if (!config) return true; + return (config.getAttribute("data-inherit-tags") || "true") === "true"; + } + function applyConfigVars(footer) { const config = getConfig(); if (!config) return; @@ -25,12 +30,12 @@ document.addEventListener("DOMContentLoaded", function () { const vars = [ "--deckroadmap-font-size", "--deckroadmap-bottom", - "--deckroadmap-active-bg-color", - "--deckroadmap-done-bg-color", - "--deckroadmap-todo-bg-color", "--deckroadmap-active-color", "--deckroadmap-done-color", - "--deckroadmap-todo-color" + "--deckroadmap-todo-color", + "--deckroadmap-active-bg-color", + "--deckroadmap-done-bg-color", + "--deckroadmap-todo-bg-color" ]; vars.forEach(function (v) { @@ -69,6 +74,45 @@ document.addEventListener("DOMContentLoaded", function () { return document.querySelector(".reveal section.present"); } + function getAllSlides() { + return Array.from(document.querySelectorAll(".reveal .slides section")); + } + +function resolveCurrentRoadmap(slide) { + if (!slide) return { mode: "neutral", value: null }; + + const explicit = slide.getAttribute("data-roadmap"); + + if (explicit === "none") { + return { mode: "hidden", value: null }; + } + + if (explicit) { + return { mode: "tagged", value: explicit }; + } + + if (!getInheritTags()) { + return { mode: "neutral", value: null }; + } + + const slides = getAllSlides(); + const currentIndex = slides.indexOf(slide); + if (currentIndex === -1) { + return { mode: "neutral", value: null }; + } + + for (let i = currentIndex - 1; i >= 0; i--) { + const tag = slides[i].getAttribute("data-roadmap"); + + if (!tag || tag === "none") { + continue; + } + + return { mode: "inherited", value: tag }; + } + + return { mode: "neutral", value: null }; +} function renderRoadmap() { const sections = getSections(); if (!sections.length) return; @@ -77,7 +121,15 @@ document.addEventListener("DOMContentLoaded", function () { if (!slide) return; const footer = ensureFooter(); - const current = slide.getAttribute("data-roadmap"); + const resolved = resolveCurrentRoadmap(slide); + + if (resolved.mode === "hidden") { + footer.style.display = "none"; + return; + } + + footer.style.display = ""; + const current = resolved.value; const currentIndex = sections.indexOf(current); footer.innerHTML = ""; @@ -93,11 +145,13 @@ document.addEventListener("DOMContentLoaded", function () { if (i < currentIndex) item.classList.add("done"); else if (i === currentIndex) item.classList.add("active"); else item.classList.add("todo"); - } else { - item.classList.add("todo"); } - item.textContent = section; + const label = document.createElement("span"); + label.className = "roadmap-label"; + label.textContent = section; + + item.appendChild(label); footer.appendChild(item); if (i < sections.length - 1) { diff --git a/man/use_roadmap.Rd b/man/use_roadmap.Rd index a83019b..7076f03 100644 --- a/man/use_roadmap.Rd +++ b/man/use_roadmap.Rd @@ -15,7 +15,8 @@ use_roadmap( todo_color = NULL, active_bg_color = NULL, done_bg_color = NULL, - todo_bg_color = NULL + todo_bg_color = NULL, + inherit_tags = TRUE ) } \arguments{ @@ -43,6 +44,10 @@ progress style.} \item{todo_bg_color}{CSS background color for upcoming sections in progress style.} + +\item{inherit_tags}{Logical; if \code{TRUE}, untagged slides inherit the most +recent \code{data-roadmap} value. Use \code{data-roadmap="none"} on a slide to hide +the roadmap entirely for that slide.} } \value{ An HTML tag with attached dependencies. diff --git a/vignettes/get-started.Rmd b/vignettes/get-started.Rmd index 825cc70..5555e2e 100644 --- a/vignettes/get-started.Rmd +++ b/vignettes/get-started.Rmd @@ -25,6 +25,8 @@ This vignette shows: - how to add a roadmap footer - how to tag slides with section names +- how section inheritance works +- how to hide the roadmap on selected slides - how to switch styles - how to preview styles before rendering slides @@ -33,7 +35,7 @@ This vignette shows: The workflow has two parts: 1. Define the sections of your presentation with `use_roadmap()` -2. Tag each slide with a matching `data-roadmap` value +2. Tag slides with matching `data-roadmap` values A minimal example looks like this: @@ -51,6 +53,8 @@ The function returns an HTML tag with the configuration and dependencies needed In a Quarto Reveal.js document, call `use_roadmap()` in an R chunk near the top of the file. +By default, you only need to tag the first slide of each section. Later slides inherit the most recent `data-roadmap` value unless you explicitly change it. + A minimal example: ````markdown @@ -74,7 +78,7 @@ use_roadmap( This is the opening slide. -## Why this matters {data-roadmap="Intro"} +## Why this matters Some framing content. @@ -82,7 +86,7 @@ Some framing content. Describe the challenge here. -## What changed {data-roadmap="Problem"} +## What changed More problem context. @@ -90,7 +94,7 @@ More problem context. Start the analysis section. -## Key findings {data-roadmap="Analysis"} +## Key findings Show results here. @@ -106,7 +110,7 @@ Discuss caveats and decisions. End with the action plan. -## Q&A {data-roadmap="Next Steps"} +## Q&A Questions. @@ -116,6 +120,8 @@ Questions. The same idea works for R Markdown Reveal.js slides. +By default, you only need to tag the first slide of each section. Later slides inherit the most recent `data-roadmap` value unless you explicitly change it. + ````markdown --- title: "deckroadmap R Markdown demo" @@ -135,7 +141,7 @@ use_roadmap( This is the opening slide. -## Why this matters {data-roadmap="Intro"} +## Why this matters Some framing content. @@ -143,7 +149,7 @@ Some framing content. Describe the challenge here. -## What changed {data-roadmap="Problem"} +## What changed More problem context. @@ -151,7 +157,7 @@ More problem context. Start the analysis section. -## Key findings {data-roadmap="Analysis"} +## Key findings Show results here. @@ -159,7 +165,7 @@ Show results here. Explain the recommendation. -## Tradeoffs {data-roadmap="Recommendation"} +## Tradeoffs Discuss caveats and decisions. @@ -167,7 +173,7 @@ Discuss caveats and decisions. End with the action plan. -## Q&A {data-roadmap="Next Steps"} +## Q&A Questions. ```` @@ -197,6 +203,29 @@ then valid slide tags include: ## Recommendation {data-roadmap="Recommendation"} ```` +## Inheriting section tags + +By default, untagged slides inherit the most recent `data-roadmap` value. This makes it easier to tag only the first slide of each section. + +For example: + +````markdown +## Intro {data-roadmap="Intro"} +## More intro content +## Problem {data-roadmap="Problem"} +## More problem detail +```` +In this example, the second slide inherits `Intro`, and the fourth slide inherits `Problem`. + +## Roadmap-free slides + +To hide the roadmap on a specific slide, use: + +````markdown +## Break slide {data-roadmap="none"} +```` +This is useful for title slides, divider slides, or transitions where you do not want the roadmap to appear. + ## Built-in styles `deckroadmap` currently includes three built-in styles. @@ -282,4 +311,6 @@ This is helpful when experimenting with styles, colors, and section names. ## Summary -`deckroadmap` provides a simple way to add section-aware roadmap footers to Reveal.js slides in Quarto and R Markdown. Define your sections once, tag slides with `data-roadmap`, choose a style, and optionally preview the result before rendering a full deck. This small amount of structure can make it easier for audiences to follow the flow of a presentation. \ No newline at end of file +`deckroadmap` provides a simple way to add section-aware roadmap footers to Reveal.js slides in Quarto and R Markdown. Define your sections once, tag slides with `data-roadmap`, choose a style, and optionally preview the result before rendering a full deck. + +By default, untagged slides inherit the most recent section, and `data-roadmap="none"` can be used to hide the roadmap on a specific slide. This small amount of structure can make it easier for audiences to follow the flow of a presentation. \ No newline at end of file