Creating a Workshop Website

February 2015

What

Create your Software Carpentry workshop website

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

Why

Allows instructors to update when they need to
Permits data to be accessible before, during, and after workshop
Ensures at least one instructor can use Git and GitHub

Overview

Create your website in a GitHub repository:
- Repo: https://github.com/username/workshop
- Branch: gh-pages
GitHub automatically turns this into a website:
- Site: http://username.github.io/workshop/
Plain pages are published as-is.
Pages with special headers are compiled.

Behind the Scenes

GitHub uses Jekyll to compile websites
Combines values from page's header...
...and from a file called _config.yml...
...with page templates stored in _layouts...
...and snippets of HTML in _includes...
...to create finished HTML pages

Behind the Scenes

Jekyll Compilation

Naming

Repositories are named YYYY-MM-DD-site

https://github.com/gvwilson/2015-07-01-miskatonic

Website has a predictable name

http://gvwilson.github.io/2015-07-01-miskatonic

Content

Put anything in the website
But index.html must contain metadata needed by main website

There's a Catch

A user can only have one fork of a repo
But instructors teach many workshops
So we cannot simply fork workshop-template
Must import the template into a new repo

Step 1: Import

Go to http://import.github.com

Enter this URL:

https://github.com/swcarpentry/workshop-template.git

Press the button to check the URL (GitHub won't import until you do)
Select the owner and name
Make sure the new repository is public

Step 1: Import

Using GitHub Import

Step 2: Customize

Go to your newly-created repository
Edit the header of index.html
Edit _config.yml to set lesson_repo and lesson_site
You can edit on GitHub or by cloning and editing on your desktop

Step 3: Check

Run tools/check.py to validate...
...tools/preview to preview locally...
...or tools/clean to clean up

4. Publish

Push to website
- If you didn't simply edit there
Check your changes
Mail URL to admin@software-carpentry.org
Or create pull request for https://github.com/swcarpentry/site that updates config/workshop_urls.yml.

Improving the Template

Fork workshop-template and send pull requests
Or file issues

Further Reading

Thank you for listening

←→

/