lesson-example
This repository shows how to create a lesson using the Software Carpentry lesson template, and is itself an example of the use of that template. Please see https://swcarpentry.github.io/lesson-example/ for a rendered version of this material, including detailed instructions on design, setup, and formatting.
Quick Instructions
-
Do not fork this repository directly on GitHub. Instead, please follow the instructions in the setup instructions to create a repository for your lesson by importing material from the styles repository.
-
Once you have created your repository, run
bin/lesson_initialize.py
to create standard lesson-specific files. You must edit several values in_config.yml
so that GitHub Pages will render your lesson correctly. -
Please read the episodes of this lesson to format your material.
-
Please keep the master copy of your lesson in your repository's
gh-pages
branch, since that is what is automatically published as a website by GitHub. -
To preview material, please run
make serve
from the command line to launch Jekyll with the correct parameters, or push to your repository'sgh-pages
branch and let GitHub take care of the rendering. -
Run
make lesson-check
to check that your files follow our formatting rules. -
If you find an error or omission in this documentation, please file an issue in this repository. If you find an error or omission in the lesson template, please file an issue in the styles repository instead.
Layout
The layout of this repository is explained in this site's episodes. 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
;_episodes/01-xyz.md
generates/01-xyz/index.html
, which can be linked to using/01-xyz/
. -
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 are stored in
_extras
. -
Figures are stored in the
fig
directory, data sets indata
, source code incode
, and miscellaneous files infiles
.
Getting Started
-
Run
bin/lesson_initialize.py
to create files that can't be stored in the template repository (because they would cause repeated merge conflicts), then edit_config.yml
as described in the documentation. -
Run
make lesson-check
at any time to check that your lesson files follow our formatting rules. If you come across formatting issues that the checker doesn't report, please file an issue in the styles repository. -
For a list of helpful commands run
make
in this directory. If you are looking for things to work on, please see [the list of issues for this repository][issues].