The Carpentries Workbench

An accessible lesson infrastructure

The Workbench is a complete redesign of The Carpentries lesson websites, with new features prioritising accessibility and navigation for Learners and Instructors. By separating the tools from the content of the lesson, The Workbench makes it easier for Maintainers and Authors to focus on the content of the lesson and not the tooling. To try it out, head over to the Resources section.

Testimonials

[The Workbench] has provided an easy way to navigate the various parts of the lesson and switch between or share the training content including instructor notes seamlessly.

— Malvika Sharan (from Celebrating The Carpentries Workbench (2023-08-21))

[editing a lesson] was pretty easy. I was doing this at the end of a long day and my brain was only half on. It seemed to just work.

— Anonymous Maintainer (from Reflecting on our first Alpha Test of the Lesson Infrastructure Redesign (2021-07-06))

three isometric hex badges for The Carpentries Workbench representing the packages sandpaper, pegboard, and varnish. Each badge is styled to look like a tiny workshop working on a wooden carpentries logo with the package namesake highlighted.

screenshot of the 'Navigating the Filesystem' episode of the Library Carpentry Shell lesson screenshot of the 'Introduction to R' episode of the Library Carpentry R for Social Scientists lesson screenshot of the 'Navigating Files and Directories' episode of the Software Carpentry Shell lesson screenshot of the 'Building Skill with Practice' episode of the Instructor Training lesson

Resources

The Workbench is built using the R language as a suite of three R packages: {sandpaper}, {pegboard}, and {varnish} that work together with R’s robust publishing ecosystem and pandoc manage and deploy Carpentries Lesson websites written in Markdown or R Markdown.

Usage

To preview a lesson that uses The Workbench, open R (or RStudio), install The Workbench, and run the following command to start a live preview that will update while you edit:

sandpaper::serve()

To preview a lesson that uses The Workbench, make sure you install The Workbench, and run the following command to start a live preview that will update while you edit:

R -e 'sandpaper::serve(quiet = FALSE, port = "3435")'

You can then open your browser to http://localhost:3435 preview your lesson as you edit.

For more guidance on The Workbench, including how create a new lesson, run accessibility tests, and more, consult our Guides

Installation

To install the workbench, make sure you have a working version of R and pandoc/RStudio installed (see the workbench setup instructions for details).

Thanks to Travis Wrightsman for providing the instructions to setup for anaconda. These lines will set up an anaconda environment that includes all the dependencies you need to use The Workbench.

conda create -n workbench 'git>=2.28' 'r-base>=3.6' 'pandoc>=2.11' pkg-config libxslt
conda activate workbench
R -e 'install.packages(c("sandpaper", "varnish", "pegboard", "tinkr"), \
  repos = list(carpentries="https://carpentries.r-universe.dev/", CRAN="https://cloud.r-project.org"))'

From there, you can install the workbench packages and their dependencies from our Carpentries R Universe inside of R:

install.packages(c("sandpaper", "varnish", "pegboard", "tinkr"),
  repos = c("https://carpentries.r-universe.dev/", getOption("repos")))

Updating

To update workbench packages, you can use the same command as you did to install your packages:

install.packages(c("sandpaper", "varnish", "pegboard", "tinkr"),
  repos = c("https://carpentries.r-universe.dev/", getOption("repos")))

Guides

Tools

Templates

Inspired Examples

These are examples of lessons developed with The Workbench since the initial announcement: