Example lesson using Software Carpentry template.
PostScript Python HTML CSS Makefile R
Permalink
Failed to load latest commit information.
_episodes Fix typo Jan 13, 2017
_episodes_rmd Merge pull request #79 from fmichonneau/add-r-pkgs Jan 9, 2017
_extras Moving links for all Jekyll-generated pages to `_includes/links.md`. Jan 8, 2017
_includes Merge branch 'gh-pages' of github.com:swcarpentry/styles into gh-pages Jan 18, 2017
_layouts Starting to incorporate Library Carpentry materials Oct 7, 2016
assets lesson.scss: 2em left padding for lists Dec 14, 2016
bin Merge remote-tracking branch 'swc-styes/gh-pages' into gh-pages Jan 9, 2017
code Preparing for June 2016 release Jun 20, 2016
data re-add ./data folder Jun 28, 2016
fig
files Preparing for June 2016 release Jun 20, 2016
.gitignore Ignoring a few more things Jul 18, 2016
.mailmap Fixing .mailmap and AUTHORS Jul 18, 2016
.update-copyright.conf .update-copyright.conf: Configure update-copyright Mar 28, 2015
AUTHORS Fixing .mailmap and AUTHORS Jul 18, 2016
CITATION Updating CITATION file Jul 19, 2016
CONDUCT.md Moving links for all Jekyll-generated pages to `_includes/links.md`. Jan 8, 2017
CONTRIBUTING.md Add reference to _episodes for lesson contribution Oct 24, 2016
LICENSE.md Merge remote-tracking branch 'swc-styes/gh-pages' into gh-pages Jan 9, 2017
Makefile Merge remote-tracking branch 'swc-styes/gh-pages' into gh-pages Jan 9, 2017
README.md Change target of setup link from .md to site page Jan 3, 2017
_config.yml Setting root values (d'oh) Sep 5, 2016
favicon-dc.ico Preparing for June 2016 release Jun 20, 2016
favicon-lc.ico Starting to incorporate Library Carpentry materials Oct 7, 2016
favicon-swc.ico Preparing for June 2016 release Jun 20, 2016
index.md Fix typo Jan 13, 2017
reference.md Adding more explanation of glossary formatting Jan 9, 2017
requirements.txt Merging from new styles Jun 15, 2016
setup.md Moving links for all Jekyll-generated pages to `_includes/links.md`. Jan 8, 2017

README.md

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

  1. 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.

  2. 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.

  3. Please read the episodes of this lesson to format your material.

  4. 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.

  5. To preview material, please run make serve from the command line to launch Jekyll with the correct parameters, or push to your repository's gh-pages branch and let GitHub take care of the rendering.

  6. Run make lesson-check to check that your files follow our formatting rules.

  7. 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:

  1. 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).

  2. 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/.

  3. If you are writing lessons in R Markdown, source files go in _episodes_rmd. You must run make 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 the fig directory.

  4. Files that appear under the "extras" menu are stored in _extras.

  5. Figures are stored in the fig directory, data sets in data, source code in code, and miscellaneous files in files.

Getting Started

  1. 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.

  2. 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.

  3. 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.