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.

TipTestimonials

[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).

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")))

All of the Workbench tools, and their dependencies, are packaged and distributed as built binaries in the form of conda packages on conda-forge for Linux, macOS, and Windows. You can setup an environment for lesson development that includes all dependencies (including R) with the following.

Pixi environments are fully reproducible by default. From the project directory, initialize a Pixi workspace

pixi init

and then add Git and the Workbench tool packages (r-pegboard is a dependency of r-sandpaper)

pixi add git r-varnish r-sandpaper

You can optionally activate a shell with the environment loaded with

pixi shell

Create a conda environment and install Git and The Workbench tool packages (r-pegboard is a dependency of r-sandpaper) from only the conda-forge channel

conda create --name workbench
conda config --name workbench --add channels conda-forge
conda config --name workbench --remove channels defaults
conda install --name workbench git r-varnish r-sandpaper

and then activate the conda environment

conda activate workbench

Updating

To update Workbench packages, you can use:

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

Guides

Tools

Templates

Inspired Examples

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