What

https://github.com/swcarpentry/lesson-template

https://github.com/swcarpentry/lesson-example

Why a Template?

1. Simplify contribution
2. Ensure uniform appearance and metadata

How

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

How

Why?

• Authors may work on many lessons
• But a user can only fork a repo once on GitHub

Template vs. Example

• lesson-template has CSS, tools, etc. that may be updated centrally
• lesson-example is explanations that shouldn't be merged into lessons over and over again
• Separate repositories are less confusing than two "main" branches in one repository

How It Works

• Make detects out-of-date source files
• Pandoc converts to HTML
• Commit the HTML to the gh-pages branch
• GitHub publishes it as a website

Why Not Jekyll?

• Workshop websites use Jekyll to create HTML
• But its Markdown lacks features we want
• And we have to do some conversion anyway
  • R Markdown
  • IPython Notebooks

1. Create Repository

• Not a fork of lesson-template
• Use GitHub Import with https://github.com/swcarpentry/lesson-template as the source URL
• Name it topic-level or topic-level-something
  • E.g., shell-novice
  • Or python-novice-inflammation
• Can be owned by anyone

2. Clone to Desktop

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

• Make sure you're not already in a Git repository
• -b gh-pages to put it in the gh-pages branch

3. Edit and Check

• See the README for general instructions
  • And lesson layout for details
  • There are notes on design
  • And an FAQ (additions welcome)
• Use make check to check conformance to template

4. Add the HTML

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

5. Push to Publish

• Push to website

$ git push origin gh-pages

• Check results at http://user.github.io/some-lesson/

When Wrong is Right

• We put generated HTML in the same branch and directory as Markdown source
• Generally a bad idea...
• ...but means paths to image and data files are the same in both...
• ...and avoids cross-branch compilation

What to Include in PRs

• Only include source Markdown files in PRs for review
  • Easier to read than generated HTML
  • Avoids each change showing up twice
• Lesson maintainers will re-generate and add HTML after PR is accepted

What's in the Template?

https://github.com/swcarpentry/lesson-template

• Page layout templates
• CSS and images
• Validation tool
  • Please run this before pushing changes

What's in the Example?

https://github.com/swcarpentry/lesson-example

• Example lesson files (home page, topics, etc.)
• Description of required files and formatting rules

Updating

• We occasionally update the CSS, icons, etc.

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

• Call the remote template rather than upstream

Source Formats

• IPython Notebooks are difficult to diff and merge
• Other formats (e.g., reStructured Text) are only used by one community

Template Contents

Sub-directories for template files

• css: style files
• img: stock images (e.g., logos)
• js: Javascript
• deck.js: Javascript for slideshows

Template Contents

Sub-directories for formatting

• _layouts: page templates
• _includes: included HTML snippets
• Named to be consistent with workshop-template

Template Contents

Sub-directory for tools

• check validates formatting
• We will add others soon

Template Contents

Makefile: do common operations

• make: Display available commands
• make check: Validate formatting
• make pages: Build pages
• make settings: Show variables and settings
• make clean: Clean up junk files

Required Files

• index.md: lesson's home page
• discussion.md: general discussion and pointers
• instructors.md: instructor's guide
• reference.md: reference guide for learners

Required Files

nn-topic.md: topics within lesson

• E.g., 01-select.md
• Each should be 10-15 minutes long

Required Files

Sub-directories for lesson files

• code: source code
• data: data files
• fig: figures

Existing Lessons

• See http://software-carpentry.org/lessons.html
• Please let us know when you start to work on another one so we can advertise it

Improving the Template

• Fork lesson-template and send pull requests as usual
• File issues when anything goes wrong, gets in your way, seems confusing, ...

Looking Ahead

• Automatically collect links to lessons on GitHub
• Issue DOIs for lessons
• Package lessons for distribution