C Adapting Existing Lessons for The Carpentries
A guide for those wishing to adapt existing lesson materials, written/published in formats other than The Carpentries lesson template, to conform to the requirements for inclusion in a Carpentries lesson program or The Carpentries Incubator.
C.1 Lesson Template
Below are some suggested approaches to incorporate previously-written lesson content into The Carpentries lesson template. Unfortunately we cannot provide detailed instructions or automated conversion for content in every format, but this section includes suggested workflows to adapt content in several of the most common formats for lessons teaching software and data skills.
C.2 Conversion from Jupyter
Jupyter notebooks in
.ipynb format can be converted to Markdown via
File -> Download as -> Markdown (.md) in the graphical Notebooks interface
or by using the
nbconvert command line tool.
convert_ipynb.py Python script,
based on the
convert.py script written by Allen Downey while developing the
Data Carpentry Astronomy curriculum,
processes Jupyter Notebooks such that, afterwards,
the Markdown derived from them
can be more readily incorporated into The Carpentries Lesson Template.
The script makes some assumptions about what your Jupyter notebooks will look like
(e.g. it looks for third-level headings beginning “Exercise” to define exercise blocks),
but it may save you some time if you have a large number of notebooks containing
a lot of code blocks etc.
To be rendered as episodes of a lesson site,
the resulting Markdown generated from the
.ipynb files processed by
will need to have YAML front matter added, before being placed in the
_episodes directory of a lesson repository (see Markdown below).
C.3 Conversion from RMarkdown
Lesson content written with RMarkdown can be directly included in the lesson template, by adding RMarkdown episodes to the
The Using Rmarkdown episode of the Lesson Example provides more details of how to write episodes in RMarkdown. Briefly, the important points are:
- You must add the episode front matter just as you would for standard Markdown.
- You should commit your RMarkdown files to the
mainbranch. The lesson build workflows have been configured such that any RMarkdown files commited to the
_episodes_rmddirectory in the
mainbranch of the GitHub lesson repository will be converted to standard Markdown and copied to the
_episodesdirectory of the
gh-pagesbranch, where the content will be served by GitHub Pages.
- You should use the
fig.altparameter to define the alternative text property for any figures/images created by code chunks in your RMarkdown.
- You will need to write the lesson landing page (
index.md), installation/setup instructions (
setup.md), Instructor Notes (
guide.md), and glossary/reference guide (
reference.md) in standard Markdown.
C.4 Conversion from other formats
Pandoc is a universal format conversion tool, which may be able to help when converting other formats (e.g. ReStructured Text) to Markdown.
Whether you have lesson content already in Markdown (e.g. from GitBook) or converted to Markdown from a Jupyter Notebook or any other format, there are some additional steps you will need to take to make this content compatible with the lesson template:
C.5.1 Set up a lesson repository
For lessons being submitted to The Carpentries Incubator:
create a new issue to
the Incubator Proposals repository
to request a new lesson repository.
After accepting an invitation, sent by email,
to join the
you will receive full administrative access to a new lesson repository
with some brief instructions to help you get started.
For lessons being developed outside The Carpentries Incubator: follow the setup instructions in the Lesson Example.
A note about the license and code of conduct: Carpentries lessons use the Creative Commons Attribution version 4.0 (CC-BY) license for lesson material, and the MIT license for any software and example code included in the lesson repository. Laws vary from country to country but, as a general rule, changing the license of a project requires explicit agreement from all previous contributors to the repository. You should make sure that you have obtained this agreement before you transfer the material into the lesson repository (which already includes the license file), or clearly state that you are re-using material originally created elsewhere (if the license of the existing material allows this). Similarly, we require that all lessons follow our Code of Conduct, and you should make sure that you and all of your collaborators have read and understand this document, and that your existing lesson material complies with the policies described in it, before you begin working in the new repository.
C.5.2 Add YAML Front Matter
The Jekyll engine that renders sites on GitHub Pages
identifies Markdown files to build into webpages based on the presence of
a header section,
known as front matter,
which is located at the top of the file.
The Technological Introductions chapter
details the fields that must be present in this YAML header.
Note: episode files written in RMarkdown must include an additional line,
source: Rmd, to be rendered correctly.
If your lesson already includes statements of learning objectives/outcomes, questions, and/or key points for each section, this information should be transferred to the YAML header for the respective episodes.
C.5.3 Add alt Text to Images
To increase the accessibility of Carpentries lessons,
all images should include a short, descriptive alternative text property.
In Markdown, alternative text (alt text) is added between the
 of the
image definition, i.e.
![Image alt text](path/to/image/file.svg)
Accessibility consultants Deque provide a good overview of the important things to consider when writing alt text, and a Medium post from Amy Cesal gives guidance on alt text for data visualisations.
C.5.4 Add to
To be built by Jekyll and included in the navigation of the resulting lesson site,
Markdown files with front matter should be located in the
_episodes directory of
your lesson repository.
Other files needed for a lesson, but not located in the
include the lesson landing page (
the installation/setup instructions (
Instructor Notes as an aid to those teaching the lesson (
and the glossary/reference guide (
You can find more complete information about these files, and others included in
the lesson template, in the Lesson Organization episode of the Lesson Example.
C.5.5 Organise supporting files
Images used as figures in the lesson should be stored in the
example code in the
and example data in
Any other supporting files that do not fit into the previous three categories
can be placed in
Remember to adjust any internal links in your lesson to match the new locations
of these files.
C.5.6 Implement formatted blocks
Some of the key visual elements of a Carpentries lesson are the boxes used for callouts, lesson prerequisites, exercises, solutions, etc. You should add the appropriate formatting to any relevant parts of your lesson, so that they render correctly. Generally speaking, this involves converting these elements to blockquotes followed by a tag that applies a CSS class to the preceding block.
See the Formatting episode of the Lesson Example for details and examples. That page also includes more information about the best way to display code blocks in the lesson template.
C.5.8 Complete Lesson Repository Setup
To finish setting up your lesson repository
- fill in any fields marked “FIXME” in the lesson
- list the names of current and past maintainers in the lesson
- update the
CITATIONfiles in the lesson repository
- add the lesson URL and topic tags to the Description of your lesson repository on GitHub
Ambrose, Susan A, Michael W Bridges, Michele DiPietro, Marsha C Lovett, and Marie K Norman. 2010. How Learning Works: Seven Research-Based Principles for Smart Teaching. John Wiley & Sons.
Jordan, Kari, François Michonneau, and Belinda Weaver. 2018. “Analysis of Software and Data Carpentry’s Pre- and Post-Workshop Surveys.” https://doi.org/10.5281/zenodo.1325464.
Wilson, Greg, Jennifer Bryan, Karen Cranston, Justin Kitzes, Lex Nederbragt, and Tracy K. Teal. 2017. “Good Enough Practices in Scientific Computing.” PLOS Computational Biology 13 (6): 1–20. https://doi.org/10.1371/journal.pcbi.1005510.