April 2015

Software Carpentry Logo


Create a new lesson for Software Carpentry


Why a Template?

  1. Simplify contribution
  2. Ensure uniform appearance and metadata


  1. Use GitHub Import to create a new repository with material from lesson-template
  2. Clone to desktop
  3. Edit according to rules in lesson-example
  4. Check
  5. Generate HTML
  6. Push to repository's gh-pages branch




Template vs. Example

How It Works

Why Not Jekyll?

1. Create Repository

2. Clone to Desktop

$ git clone -b gh-pages git@github.com:user/some-lesson.git

3. Edit and Check

4. Add the HTML

  1. make preview to create HTML
  2. git add *.html
  3. git commit -m "Adding HTML"

5. Push to Publish

$ git push origin gh-pages

When Wrong is Right

What to Include in PRs

What's in the Template?


What's in the Example?



$ git remote add template https://github.com/swcarpentry/lesson-template.git
$ git pull template gh-pages

Source Formats

You can use any source format you want
as long as (a) it can be diffed and merged
and (b) the Makefile translates it into Markdown
that conforms to our style guide

Template Contents

Sub-directories for template files

Template Contents

Sub-directories for formatting

Template Contents

Sub-directory for tools

Template Contents

Makefile: do common operations

Required Files

Required Files

nn-topic.md: topics within lesson

These are for instructors and offline reference,
not to be shown to learners during teaching

Required Files

Sub-directories for lesson files

Existing Lessons

Improving the Template

Issues related to workflow are (at least) as welcome
as issues related to content

Looking Ahead

Thank you for listening

Software Carpentry Logo