Frequently Asked Questions
As this is a FAQ, it will continue to grow as we update it. If you have any questions please submit them to the Workbench GitHub discussion forum.
I will attempt to divide these questions up by major categories, but these may shift around as questions come in.
If you have a question about definitions, consult our glossary
Teaching
GitHub Forks
How do I create a fork for teaching?
A common pattern for teaching is to create a fork of a lesson, modify it to add or remove specific section. Because the pages on The Workbench are deployed by GitHub actions, there are a couple of extra steps you need to do to enable the pages to load after the transition.
In short, when you fork, to make it easier, you should bring in all branches, enable GitHub pages, and enable GitHub Actions. After that, you will have your lesson website and can teach from it.
You can find the instructions in issue 14 of the Dovetail blog series.
Workshop Websites
How do I add episodes to my workshop website?
Before 2020, instructors were occasionally encouraged to copy the episodes from a lesson into their workshop website to avoid situations where the lesson would change significantly while the workshop was being taught. In short, you can not do this. Instead, you can make a fork of the lesson and link that on your workshop website.
In the future, we will implement lesson versioning where you will be able to select a specific version of a lesson to teach from, so that you can always be sure that the content is stable.
The website https://htmlpreview.github.io allows you to display HTML pages hosted on GitHub without needing to set up GitHub pages. If you do not want to fork, but still want a working version you can teach from, you can head to a workbench repository, select the gh-pages
branch, select the index.html
file and click on copy permalink
and paste that into html preview:
For example: this is the workbench documentation as of 2023-02-07: https://htmlpreview.github.io/?https://github.com/carpentries/sandpaper-docs/blob/59651a69e7716c04edaf8f9c1c79abc18ce3e476/index.html
This is a very workable version of the lesson (with some styling differences as the default font could not be loaded).
The only catch is that you have to manually switch to instructor view by the URL: https://htmlpreview.github.io/?https://github.com/carpentries/sandpaper-docs/blob/59651a69e7716c04edaf8f9c1c79abc18ce3e476/instructor/index.html
And there you have a quick version of the lesson.