Customizing HPC Carpentry Material

Last updated on 2026-02-20 | Edit this page

Estimated time: 52 minutes

Overview

Questions

  • Where are the files I need to edit?
  • What parameters should I set?
  • What might my cluster’s admins help me with?
  • When should I make a new snippet? How?

Objectives

  • Explain how to customize the site for your cluster
  • Instruct how to build and serve the site
  • Demonstrate how to include pieces of code, output, and custom teaching material

Introduction

Every compute cluster is a little different, and HPC Carpentry works best when the lesson materials reflect those differences. We use the Workbench built-in tools and R Markdown to render this customizxed content, structured with maintainability in mind. We want to support edits without breaking synchronization with the upstream repositories: you have good ideas, and we want to incorporate better preactices!

Inline instructor notes can help inform instructors of timing challenges associated with the lessons. They appear in the “Instructor View”

Challenge

Challenge 1: Can you do it?

What is the output of this command?

R 

paste("This", "new", "lesson", "looks", "good")

OUTPUT 

[1] "This new lesson looks good"
Challenge

Challenge 2: how do you nest solutions within challenge blocks?

You can add a line with at least three colons and a solution tag.

Figures

You can use standard markdown for static figures with the following syntax:

![optional caption that appears below the figure](figure url){alt='alt text for accessibility purposes'}

Blue Carpentries hex person logo with no text.
You belong in The Carpentries!
Callout

Callout sections can highlight information.

They are sometimes used to emphasise particularly important points but are also used in some lessons to present “asides”: content that is not central to the narrative of the lesson, e.g. by providing the answer to a commonly-asked question.

Math

One of our episodes contains \(\LaTeX\) equations when describing how to create dynamic reports with {knitr}, so we now use mathjax to describe this:

$\alpha = \dfrac{1}{(1 - \beta)^2}$ becomes: \(\alpha = \dfrac{1}{(1 - \beta)^2}\)

Cool, right?

Key Points
  • Use .md files for episodes when you want static content
  • Use .Rmd files for episodes when you need to generate output
  • Run sandpaper::check_lesson() to identify any issues with your lesson
  • Run sandpaper::build_lesson() to preview your lesson locally