previous episode

Lesson Title

next episode

Lesson Organization

Overview

Teaching: 10 min
Exercises: 0 min
Questions

  • How are the files in a lesson organized?

Objectives

  • Explain overall organization of lesson files.

Each lesson is made up of episodes, which are focused on a particular topic and include 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:

Source and Destination Files

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.

Helper Files

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.

Standard Files

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:

Starter Files

The bin/lesson_initialize.py script creates files that need to be customized for each lesson:

CONTRIBUTING.md
Contribution guidelines. The 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
The Jekyll configuration file. This must be edited so that its links and other settings are correct for this lesson.
  • carpentry should be either “dc” (for Data Carpentry), “lc” (for Library Carpentry), “swc” (for Software Carpentry), “cp” (for Carpentries), or “incubator” (for lessons in The Carpentries Incubator).
  • title is the title of your lesson, e.g., “Defence Against the Dark Arts”.
  • email is the contact email address for the lesson.
CITATION
A plain text file explaining how to cite this lesson.
AUTHORS
A plain text file listing the names of the lesson’s authors.
index.md
The home page for the lesson.
  1. It must use the lesson layout.
  2. It must not have a title field in its YAML header.
  3. It must open with a few paragraphs of explanatory text.
  4. That introduction must be followed by a single .prereq blockquote detailing the lesson’s prerequisites. (Setup instructions appear separately.)
  5. That must be followed by inclusion of syllabus.html, which generates the syllabus for the lesson from the metadata in its episodes.
reference.md
A reference guide for the lesson. The template will automatically generate a summary of the episodes’ key points.
  1. It must use the reference layout.
  2. Its title must be "Reference".
  3. It should include a glossary, laid out as a description list.
  4. It may include other material as appropriate.
setup.md
Detailed setup instructions for the lesson. Note that we usually divide setup instructions by platform, e.g., include level-2 headings for Windows, macOS, and Linux with instructions for each. The workshop template links to the setup instructions for core lessons.
  1. Its title must be "Setup"..
  2. It should include whatever setup instructions are required.
_extras/about.md
General notes about this lesson. This page includes brief descriptions of The Carpentries, and is a good place to put institutional acknowledgments.
_extras/discussion.md
General discussion of the lesson contents for learners who wish to know more: This page normally includes links to further reading and/or brief discussion of more advanced topics.
  1. Its title must be "Discussion".
  2. It may include whatever content the author thinks appropriate.
_extra/figures.md and _includes/all_figures.html
Does nothing but include _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
The instructors’ guide for the lesson. This page records tips and warnings from people who have taught the lesson.
  1. Its title must be "Instructors' Guide".
  2. It may include whatever content the author thinks appropriate.

Figures

All figures related with the lesson must be placed inside the directory fig at the root of the project.

RMarkdown

Episodes may also be written with RMarkdown. Save RMarkdown episode files with the extension .Rmd in the _episodes_rmd directory. These will be converted to Markdown files when the lesson site is built. The resulting .md files will be saved to the _episodes directory, where they will form part of the Episodes collection.

See the Using RMarkdown episode for more information about writing lessons with RMarkdown.

Episode Order

By default, the order of Episodes and Extras in the lesson is determined by the name of the file, e.g. an episode with the filename 01-introduction.md appears before a lesson with the filename 02-cheese-rolling.md. To override this default ordering, define the episode_order and/or extras_order parameters in _config.yml. The value of these parameters should be an array of filenames with the extension removed, e.g.

episode_order:
    - introduction
    - first_steps
    - running
    - jumping
    - gymnastics
    - olympics
    - conclusion

Some lesson developers have found this useful when using the lesson template to create more modular material and/or when working with material in the early stages of development that is likely to be added to and reorganised. Any files in the relevant collection folder (e.g. _episodes) not included in the array will be omitted from the lesson navigation (but will still be built).

Ordering RMarkdown Episodes

Regardless of whether episode_order has been defined in _config.yml to determine the order that episodes appear in the lesson site, episodes written in RMarkdown will always be executed and converted to Markdown in alphabetical order. If a lesson contains multiple episodes in RMarkdown and these episodes depend on each other e.g. variables created in one episode are used in another, care should be taken to ensure these episodes are executed in the correct order. In these cases, it is recommended to adopt a numeric naming system for episode files e.g. 01-getting-started.Rmd, 02-loading-data.Rmd etc.

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.

previous episode

next episode