Summary and Setup

Welcome to the documentation for The Carpentries Workbench.

The Workbench is a suite of tools that takes lesson material content written in simple text, and builds a neat and consistent static website.

It is built on Git, the R language, and pandoc, and consists of four components:

  1. The source content, i.e. the “lesson” (plain markdown or RMarkdown files organized into folders with a configuration yaml file)
  2. The engine (R package {sandpaper}) to process the lesson content markdown to HTML
  3. The validator (R package {pegboard}) to parse the source markdown files and highlight common errors
  4. The renderer (R package {varnish}) to generate the final HTML, CSS, and JavaScript styling elements for the lesson website

Details of how these tools work together are explained in the Workbench Internals documentation. In short, you can interact with the lesson source content and the Workbench tools to author and preview your lesson.

Working examples of Workbench-powered lessons can be found as part of our Carpentries curriculum:

Checklist

Features of the The Carpentries Workbench

To get started using the Workbench, continue reading below!

Installation of the Workbench

We provide four mechanisms to interact with the Workbench:

  • Devcontainers (online or local) [recommended]
    • We recommend using devcontainers as everything will be installed for you whether you are using an online or local environment, with minimal setup.
    • Lessons with devcontainer support will have a .devcontainer folder in the root of the repository.
    • If no devcontainer is available for the lesson you wish to work on, please use the manual installation route, or Docker if you are comfortable with it.
  • Docker (local)
    • The Docker option can be useful for those that already have experience with Docker and containers, and are happy to do some manual configuration or wish to have more flexibility.
    • Initial setup with docker is very straightfoward but can get complicated depending on your operating system!
  • Manual local installation from conda-forge with Pixi (local)
    • Installing all the requirements for development is one line and will create a fully reproducible environment.
    • Initial setup with conda packages from conda-forge and Pixi is very straightfoward and is operating system agnostic.
  • Manual local installation with operating system specific tools (local)
    • Installing all the requirements manually on your local operating system is a longer process, but can be useful if you want to learn how to get an environment set up and will teach you more about the Workbench framework.
    • If Docker and devcontainers are not suitable for you, installing things manually is a great option and still relatively quick to do!
  • GitHub (online)
    • Moving your development completely online by using GitHub’s Codespaces or Dev environment is an excellent choice if you have a reliable internet connection and are comfortable with this process.
    • Be advised that this option may incur a cost depending on your GitHub account status!
Callout

Why would I want to install locally if all these other options exist?

You can use the Workbench completely within devcontainers, Docker, or with Pixi locally, or through GitHub using our templates.

However, we still would recommend working through the local setup instructions at least once as they can save you a lot of time during lesson development and debugging in future.

Once your installation is complete with one of the mechanisms above, make sure to test your installation using the instructions below.

Test your Workbench installation

To test your installation open RStudio either as the locally installed app or in the browser if using Docker (or launch R if you have not installed RStudio and are not using Docker/devcontainers) and enter the following commands to confirm everything works:

R 

rmarkdown::pandoc_version()
tmp <- tempfile()
sandpaper::no_package_cache()
sandpaper::create_lesson(tmp, open = FALSE)
sandpaper::build_lesson(tmp, preview = FALSE, quiet = TRUE)
fs::dir_tree(tmp, recurse = 1)

OUTPUT 

[1] '3.9'
ℹ Consent for package cache revoked. Use `use_package_cache()` to undo.
→ Creating Lesson in '/tmp/RtmpnRjHyr/file12f34734be05f'...
✔ First episode created in '/tmp/RtmpnRjHyr/file12f34734be05f/episodes/01-introduction.Rmd'
ℹ Workflows up-to-date!
✔ Lesson successfully created in '/tmp/RtmpnRjHyr/file12f34734be05f'
/tmp/RtmpnRjHyr/file12f34734be05f
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE.md
├── README.md
├── config.yaml
├── episodes
│   ├── 01-introduction.Rmd
│   ├── data
│   ├── fig
│   └── files
├── index.md
├── instructors
│   └── instructor-notes.md
├── learners
│   └── setup.md
├── profiles
│   └── learner-profiles.md
└── site
    ├── DESCRIPTION
    ├── README.md
    ├── _pkgdown.yaml
    ├── built
    └── docs

If the installation did not work, please raise an issue on GitHub.

Connect to GitHub

To share your lessons with others, and to use our provided automated build and publishing workflows, you will need to use GitHub.

Setting up Git

You will need to make sure your git session is connected to GitHub. If you already push and pull from GitHub using the command line, you do not need to worry about setting this up as you will have done so already.

If you haven’t used git or GitHub before, we recommend working through our Software Carpentry Git lesson first.

To do so, you will need to use an SSH or HTTPS protocol. It’s recommended to use the SSH protocol, unless you explicitly cannot, e.g. behind an institutional firewall or proxy. If you do not have this set up, you should choose a protocol and then set them up according to the instructions from GitHub.

Callout

Docker/devcontainers and git

If you already have your git installation configured outside the Docker/devcontainer environment, the various scripts and commands used in this documentation include mapping your local SSH (and GPG signing) configuration into the container. This means your git commands should “just work” inside the container as they would outside.

If you have any issues, please open an issue on the workbench-docker GitHub repo and/or ask for help on the workbench channel in The Carpentries Slack workspace.

Callout

Is GitHub’s Documentation Confusing?

You may find GitHub’s documentation slightly confusing and/or lacking. The following resources are extremely helpful for setting up authentication credentials for your account:

Remotes in GitHub (Software Carpentry)
A walkthrough of creating a repository on GitHub and pushing to it via the command line.
Connect to GitHub (Happy Git With R)
A walkthrough of creating a throwaway repository that gives you a good idea for the mechanics of working with GitHub.
Cache credentials for HTTPS (Happy Git With R)
Clear explanation on how to set up a Personal Access Token and the benefits of using HTTPS. This explains how to do this in both the shell and R.
Set up keys for SSH (Happy Git With R)
Clear explanation on what SSH key pairs are and how to set up and connect them with GitHub. This has recommendations using both the shell and RStudio.