index.qmd

---
title: The Carpentries Workbench
subtitle: An accessible lesson infrastructure
---

The Workbench is a [complete redesign of The Carpentries lesson
websites](https://carpentries.org/blog/2020/08/lesson-template-design/), 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](#resources).

::: {.callout-tip}

## 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)](https://carpentries.org/blog/2023/08/celebrating-carpentries-workbench/))

 > [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)](https://carpentries.org/blog/2021/07/infrastructure-testing/))

:::

<figure style='text-align: center'>
<p>
<img src="fig/hex-collection.jpeg" width="50%" alt="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.">
<div class='column-screen-inset' style='text-align: left'>
<img src="fig/lc-workbench.png" width="23%" alt="screenshot of the 'Navigating the Filesystem' episode of the Library Carpentry Shell lesson">
<img src="fig/dc-workbench.png" width="23%" alt="screenshot of the 'Introduction to R' episode of the Library Carpentry R for Social Scientists lesson">
<img src="fig/swc-workbench.png" width="23%" alt="screenshot of the 'Navigating Files and Directories' episode of the Software Carpentry Shell lesson">
<img src="fig/cp-workbench.png" width="23%" alt="screenshot of the 'Building Skill with Practice' episode of the Instructor Training lesson">
</div>
</p>
</figure>

## Resources

The Workbench is built using the [R language](https://r-project.org) as a suite
of three R packages: [{sandpaper}], [{pegboard}], and [{varnish}] that work
together with R's robust publishing ecosystem and [pandoc](https://pandoc.org)
manage and deploy Carpentries Lesson websites written in Markdown or R Markdown.


### Usage

::: {.panel-tabset}

#### Within R

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

```r
sandpaper::serve()
```

#### From the command line

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

```bash
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](#guides)


### Installation

:::: {.panel-tabset}

#### Within R

To install the Workbench, make sure you have a working version of R and
pandoc/RStudio installed (see [the Workbench setup instructions for
details](https://carpentries.github.io/sandpaper-docs/)).

From there, you can install the Workbench packages and their dependencies from
our [Carpentries R Universe](https://carpentries.r-universe.dev) inside of R:

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

#### From conda-forge

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

::: {.panel-tabset}

##### With Pixi

[Pixi](https://pixi.sh/) environments are fully reproducible by default.
From the project directory, initialize a Pixi workspace

```sh
pixi init
```

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

```sh
pixi add git r-varnish r-sandpaper
```

You can optionally activate a shell with the environment loaded with

```sh
pixi shell
```

##### With Conda

Create a [conda](https://docs.conda.io/) environment and install Git and The
Workbench tool packages (`r-pegboard` is a dependency of `r-sandpaper`) from
only the `conda-forge` channel

```sh
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

```sh
conda activate workbench
```

:::

::::

### Updating

To update Workbench packages, you can use:

::: {.panel-tabset}

#### R

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

#### Pixi

```sh
pixi update
```

#### Conda

```sh
conda update --name workbench r-tinkr r-varnish r-pegboard r-sandpaper
```

:::


### Guides

 - [Glossary](reference.html#glossary) A glossary of terms for the Workbench.
 - [Official Workbench Documentation](https://carpentries.github.io/sandpaper-docs): written using the Workbench, this guide provides everything you need to get started using the Workbench.
 - [Collaborative Lesson Development Training](https://carpentries.github.io/lesson-development-training/): Material for a three day workshop teaching good practices in lesson design and open source collaboration skills

### Tools

 - [{sandpaper}]\: User interface and engine for the Workbench
 - [{pegboard}]\: Validation and parsing of lesson components
 - [{varnish}]\: HTML, CSS, and JavaScript templates
 - [(carpentries/actions)](https://github.com/carpentries/actions#readme): GitHub Actions for Workbench Workflows
 - [(carpentries/lesson-transition)](https://github.com/carpentries/lesson-transition): Tool for automated transition from styles-based lessons to Workbench.

### Templates

 - [R Markdown Lesson Template](https://github.com/carpentries/workbench-template-rmd)
 - [Markdown Lesson Template](https://github.com/carpentries/workbench-template-md)


### Inspired Examples

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

- Toby Hodges, Mateusz Kuzak, Aleksandra Nenadic, Sarah Stevens---[Collaborative Lesson Development Training](https://carpentries.github.io/lesson-development-training/)
- Saranjeet Kuar, Achintya Rao, Heather Turner, Aman Goel---[R's Bug Tracking](https://contributor.r-project.org/r-bug-tracking-lesson/)
- Saba Ferdous, David Pérez-Suárez---[Learn To Discover---Basic Python](https://learntodiscover.github.io/Basic_Python/) (note---this uses a custom fork of sandpaper, and varnish to run python)
- Philipp Matthias Schäfer---[GitLab Novice](https://zedif.github.io/gitlab-novice/)
- Michael Culshaw-Maurer---[Rewrite of the R Ecology Lesson](https://www.michaelc-m.com/Rewrite-R-ecology-lesson/)

### Stay in Touch
Join [the Workbench mailing list](https://carpentries.topicbox.com/groups/workbench) and/or the `#workbench` channel on [The Carpentries Slack Workspace](https://slack-invite.carpentries.org/) to receive news about the Workbench, announcements of new version releases, etc.



[{sandpaper}]: https://carpentries.github.io/sandpaper/ "User interface and engine for the Workbench"
[{pegboard}]: https://carpentries.github.io/pegboard/ "Validation and parsing of lesson components"
[{varnish}]: https://carpentries.github.io/varnish/ "HTML, CSS, and JavaScript templates"