Overview
Teaching: 10 min
Exercises: 0 minQuestions
How are the files in a lesson organized?
Objectives
Explain overall organization of lesson files.
Each lesson is made up of episodes that are 10-30 minutes long (including time for both teaching and exercises). The episodes of this lesson explain the tools we use to create lessons and the formatting rules those lessons must follow.
Why “Episodes”?
We call the parts of lessons “episodes” because every other term (like “topic”) already has multiple meanings, and because it encourages us to think of breaking up our lessons into chunks that are about as long as a typical movie scene, which is better for learning than long blocks without interruption.
Our lessons need artwork, CSS style files, and a few bits of Javascript. We could load these from the web, but that would make offline authoring difficult. Instead, each lesson’s repository is self-contained.
The diagram below shows how source files and directories are laid out, and how they are mapped to destination files and directories:
Collections
As described earlier, files that appear as top-level items in the navigation menu are stored in the root directory. Files that appear under the “extras” menu are stored in the
_extras
directory, while lesson episodes are stored in the_episodes
directory.
As is standard with Jekyll sites,
page layouts are stored in _layouts
and snippets of HTML included by these layouts are stored in _includes
.
Each of these files includes a comment explaining its purpose.
Authors do not have to specify that episodes use the episode.html
layout,
since that is set by the configuration file.
Pages that authors create should have the page
layout unless specified otherwise below.
The assets
directory contains the CSS, Javascript, fonts, and image files
used in the generated website.
Authors should not modify these.
When the lesson repository is first created,
the initial author should create a README.md
file containing
a one-line explanation of the lesson’s purpose.
The lesson template provides the following files which should not be modified:
CONDUCT.md
: the code of conduct.LICENSE.md
: the lesson license.Makefile
: commands for previewing the site, cleaning up junk, etc.The bin/lesson_initialize.py
script creates files that need to be customized for each lesson:
CONTRIBUTING.md
issues
and repo
links at the bottom of the file must be changed
to match the URLs of the lesson:
look for uses of FIXME
._config.yml
carpentry
should be either “dc” (for Data Carpentry) or “swc” (for Software Carpentry).title
is the title of your lesson,
e.g.,
“Defence Against the Dark Arts”.email
is the contact email address for the lesson.CITATION
AUTHORS
index.md
lesson
layout.title
field in its YAML header..prereq
blockquote
detailing the lesson’s prerequisites.
(Setup instructions appear separately.)syllabus.html
,
which generates the syllabus for the lesson
from the metadata in its episodes.reference.md
reference
layout."Reference"
./reference/
.setup.md
page
layout."Setup"
./setup/
._extras/about.md
_extras/discussion.md
page
layout."Discussion"
./discuss/
._extra/figures.md
and _includes/all_figures.html
_includes/all_figures.html
,
which is (re)generated by make lesson-figures
.
This page displays all the images referenced by all of the episodes,
in order,
so that instructors can scroll through them while teaching._extras/guide.md
page
layout."Instructors' Guide"
./guide/
.Key Points
Auxiliary files are stored in the _layouts, _includes, and assets directories.
The code of conduct, license, Makefile, and contribution guidelines should not be modified.
The README, authors’ list, and citation instructions must be updated for each lesson.
The home page, reference guide, setup instructions, discussion page, and instructors’ guide must be updated for each lesson.
The Makefile stores commonly-used commands.