The learnr package is designed to be used with a wide variety of R Markdown formats. A tutorial is simply a directory containing an R Markdown document which:
Loads the learnr package.
Includes one or more interactive components (exercises, quiz questions, etc.).
runtime: shiny_prerendereddirective in the YAML header.
Uses a format which inherits from the
html_document_baseformat and is marked as
boostrap_compatible(this is a parameter of
html_document_basewhich indicates that it’s safe to inject Booststrap CSS into the document).
We’ve shown plenty of examples of the default format, here’s an example of embedding a tutorial within a
You can run a live version of this example with:
learnr::run_tutorial("slidy", package = "learnr")
The learnr package includes a
learnr::tutorial R Markdown format which which provides some default layout and behavior (including progress tracking) which you’ll likely want to use in many of your tutorials.
The format also includes features for progressively revealing sections and allowing users to optionally skip exercises they are having trouble with (both of these features are described below).
You can create a new
learnr::tutorial document from a template via the New R Markdown dialog in RStudio:
The benefits of using the
learnr::tutorial format include:
More appropriate defaults are provided for various things including figure sizes and data frame printing.
A floating table of contents for easy navigation between sections is provided by default.
Visual adornments are added to the table of contents indicating which parts of the tutorial have been completed.
A “Start Over” button is added to the table of contents region to allow users to clear previous work within the tutorial.
Here’s what a
learnr::tutorial document looks like by default:
The implementation of the
learnr::tutorial format is extremely straightforward and provides a template for creating additional new formats via the API:
The tutorial-format.R file includes the definition of the custom R Markdown format function.
The inst/rmarkdown/templates/tutorial directory includes all the files and configuration required to make the format available as a custom R Markdown template within the RStudio IDE.