This folder contains the python script and yaml file used by the build_lesson_wf.yml workflow file (which can be found in .github/workflows) to properly structure the lesson and generate the slides markdown file (which can be found in the slides folder).
By "structure the lesson" we mean the following:
- Sorting the episodes correctly, according to the order defined in the lesson_structure.yml file.
- Adding a prefix to the episode files' names, as well as to their titles (defined in a YAML header at the top of each episode file), encoding its number (relative to their order in the lesson) and the number of the session it belongs to (for more details regarding this part read below).
By "generate the slides markdown file" we mean the following:
- Extracting the (properly tagged) content from all the episode files and putting it all into one file called slides.md (in the slides folder).
All files are thorougly commented according to the same commenting layout template.
This refers to the content that can be seen by reading the files on Github, either through the markdown viewer or by accessing the files' raw format. The former will allow you to see everything in a text file, apart from html comments, while the latter will let you see even those same html comments.
This refers to the content that will show up on the website generated by Jekyll/GitHub Pages. It includes everything except html comments and liquid comments. The latter are written down as:
{%comment%}
This is a Liquid comment
{%endcomment%}
Liquid is a template language used by Jekyll.
Within the the Liquid comments, one can tag content meant to show up on the slides, but not on the website. The tag itself can be easily modified in the build_lesson.py script, by changing the string assigned to the slidesTag variable. Currently, the tag is $$$. See the example below:
{%comment%}
Some comment.
$$$
This content will only be shown on the slides.
$$$
Some other comment.
{%endcomment%}
If you wish to change the slides tag, just look under the 'PRELIMINARY DEFINITIONS AND OPERATIONS' section, in the build_lesson.py script:
# ----------------------------------------------------------------
# ------------ PRELIMINARY DEFINITIONS AND OPERATIONS ------------
# ----------------------------------------------------------------
# We first import some libraries and define some variables and functions that will be useful.
Under this section you will find, at one point, the following piece of code:
# The slides tag. Change it here if you wish to use another tag for the content of the slides.
slidesTag = "$$$"
You can change the slidesTag variable to whatever string you wish. Keep in mind, though, that if you do that you should also change the tag in the episode files where it is used, otherwise the slides content will not be properly identified by the build_lesson.py script.