This lesson template is intended to be used with the workshop-template, but could still be used to create an independent, standalone lesson. It is based on the Carpentries lesson example, but with some modifications. The aim is to keep this template as simple and up-to-date with the Carpentries example as possible.
-
Create a new lesson by creating a template of this repository, ensure that the branch is still named gh-pages. Please make sure to create this in the Southampton-RSG-Training organization, with a short name such as "git-novice", or "shell-advanced".
-
Optionally, you should immediately create a new branch for the lesson you are creating. By using branches, it is possible to create a collection of the same lesson customized for different audiences which can be easily re-used in the future in the workshop template.
-
You need to edit several variables in
_config.yml
for the lesson to render correctly.
When making a lesson to be used with the workshop template, to ensure that your
lesson is a consistent style with the other lessons, please use the episode
layout, i.e. ensure that layout: episode
is in the front matter, or do not
specify a layout at all.
Each lesson included in a workshop has a top level and a detailed schedule. The
detailed schedule is automatically generated, however the top level one may need
some manual changes. This schedule is located in _includes/rsg/schedule.html
,
and will need some knowledge of HTML to modify. However, the default schedule is
probably okay for most circumstances.
If your lesson takes place over multiple days, then _includes/rsg/schedule.html
will need to include two schedule tables. Additionally, for the first
lesson episode for each day, you need to place start: true
in the front
matter. This will then mark where each day starts and ends in the detailed
lesson schedule.
To make full use of the lesson template, it is wise to include as many as the following front matter variables in your episodes:
title
- the episode titleslug
- the episode slug, used as the permalink to that episodeteaching
- the number of minutes of teaching for the episodeexercises
- the number of minutes of exercises for the episodequestions
- a YAML list of questions for the episodeobjectives
- a YAML list of episode objectiveskeypoints
- a YAML list of episode key pointsstart
- either true or false, to indicate if a lesson is the first of a day
The title
, slug
, teaching
and exercises
variables are required, the
others are optional and the layout of the page will adjust accordingly to what
has been included.
You should only need to update the following files:
index.md
setup.md
reference.md
_includes/rsg/schedule.html
- Lesson markdown files in
_episodes
/_episode_rmd
- Lesson extras in
_extras
_config.yml
The layout of lessons is nominally explained [here] (https://carpentries.github.io/lesson-example/03-organization/index.html). But, in brief:
-
The source for pages that appear as top-level items in the navigation bar are stored in the root directory, including the home page (
index.md
), the reference page (reference.md
), and the setup instructions (setup.md
). -
Source files for lesson episodes are stored in
_episodes
. As a standalone lesson,01-introduction.md
would generate/01-introduction/index.html
. As part of the workshop template, the generated page is instead generated to the slug of the markdown file. -
If you are writing lessons in R Markdown, source files go in
_episodes_rmd
. You must runmake lesson-rmd
to turn these into Markdown in_episodes
and commit those Markdown files to the repository (since GitHub won't run anything except Jekyll to format material). You must also commit any figures generated from your lessons, which are stored in thefig
directory. -
Files that appear under the "extras" menu in the lesson navigation bar are stored in
_extras
. -
Figures are stored in the
fig
directory, data sets indata
, source code incode
, and miscellaneous files infiles
.