Home Original page

The Carpentries Workbench

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.

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:

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

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

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

Updating

To update Workbench packages, you can use:

install.packages(c("sandpaper", "varnish", "pegboard", "tinkr"),
  repos = c("https://carpentries.r-universe.dev/", getOption("repos")))
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: