Reference
Glossary
Below are terms used in association with The Carpentries Workbench.
- workbench
- the collection of three packages used to build Carpentries lessons. NOTE: this is no longer called the “template”.
- lesson source
- a collection of standard files and folders generated from a [lesson template])#template) that The Workbench uses to build a lesson website
- lesson website
- An HTML website built by The Workbench.
- {sandpaper}
- the package that lesson contributors interact with. This orchestrates the building of lessons from markdown/rmarkdown to html
- {pegboard}
- the validator for our lesson content.
- {varnish}
- html, css, and javascript styling for our lessons.
- carpentries/actions
- Automation for deploying and updating our lessons on GitHub
- template
- A standard set of files that are used to create a Carpentries lesson. The lesson author is expected to customise and modify these files with their own custom lesson content.
- Markdown Lesson Template
- https://bit.ly/new-lesson-md a GitHub repository template to create a new lesson written in markdown using The Workbench
- R Markdown Lesson Template
- https://bit.ly/new-lesson-rmd a GitHub repository template to create a new lesson written in R Markdown using The Workbench
- Official Lessons
- Lessons within our Official Curriculum that are offered in Centrally-Organised or Self-Organised workshops. Community Lessons Lessons that are developed by community members, but are not offered in centrally-organised workshops
- Toolchain
- A series of software tools that work together to accomplish a specific task. E.g. The Carpentries Workbench is a toolchain built with R and pandoc to publish accessible lesson websites from markdown or R Markdown content.
- Styles (aka lesson template)
- This is the lesson infrastructure established in 2016 and can be found at https://github.com/carpentries/styles. It uses Jekyll for rendering markdown to HTML with a Make-based workflow. The Carpentries Workbench supersedes this infrastructure. This particular infrastructure required that the tools and templates were embedded within the lesson itself, meaning that updates were often cumbersome.
- Lesson infrastructure
- The collection tools and templates required to build Carpentries-style lessons.
- Lesson-transition tool
- A custom toolchain that prepared existing lessons to use The Carpentries Workbench: https://github.com/carpentries/lesson-transition. This would transform markdown syntax from Kramdown to Pandoc-flavoured markdown and it would remove commits unrelated to the lesson content.
- Jekyll
- A static site generator that is used by default to build websites on GitHub from markdown.
- Kramdown
- The default flavour of markdown used by Jekyll. It is originally based off of a PHP variant of the original markdown syntax that is not widely used.
- Pandoc-flavoured markdown
- A style of markdown that is derived from CommonMark and is the basis for the pandoc document converter https://pandoc.org/MANUAL.html#pandocs-markdown.
- Fishtree Attempt
- GitHub organisation to host testing repositories of the transformed lessons.
- Beta Phase
- This is the phase in which lessons are tested with maintainers, instructors, and learners to evaluate any potential snags in the websites that should be fixed before converting all of our lessons. This is divided into three stages for each lesson.
- Pre-beta stage (8 weeks)
-
a snapshot of a lesson is converted to the workbench in a separate github organisation and hosted on a temporary url (
preview.carpentries.org/<lesson>). A banner is hosted on the github URL indicating a beta test with a link to the new url. - Beta stage (8 weeks)
-
a lesson release and archive is created. The lesson is converted to the workbench and hosted on (preview.carpentries.org/
). The github URL hosts the snapshot of the lesson at the given release and has a link to the new URL, indicating that it is the up-to-date version. - Release Candidate (24 weeks)
- The default URL will now show the Workbench version of the lesson and the styles version of the lesson will be archived. During this time, any imperfections in the transition are to be addressed by the maintainers.