A New Template for Workshop Websites

This post originally appeared on the Software Carpentry website.

The first step in reorganizing the bc repository is making it easier (much easier) for people to create websites for workshops. The current instructions are almost 3000 words long, and even experienced GitHub users find the process daunting, so we're going to simplify things as much as we can, even if that means not doing things the "right" way.

Background

1. If a repository has a branch called gh-pages (which stands for "GitHub pages"), then GitHub uses the HTML and Markdown files in that branch to create a website for the repository. If the repository's URL is http://github.com/darwin/finches, the URL for the website is http://darwin.github.io/finches.

2. If an HTML or Markdown file has a header consisting of three dashes, some data about the page, and three more dashes:

   ---
   key_1: value_1
   key_2: value_2
   ---
   page contents
   

   then GitHub doesn't just copy the file over verbatim. Instead, it runs the file through a translator called Jekyll that processes instructions embedded in the file to generate the final HTML.

3. One of these instructions is {{variable}}. When Jekyll sees this, it replaces the curly braces and the variable's name with the value of variable. This is used to insert things like contact email addresses into the page. (Variables from the page's header actually have to be referred to as {{page.variable}}, rather than simply as {{variable}}, because Jekyll can also get variables in other ways that we're not using.)

4. If a page like index.html has a variable called layout, and that variable's value is standard.html, Jekyll looks for a file call _layouts/standard.html and uses it as a template for laying out the page. This is used to give the pages in a site a uniform appearance.

Setup

Here's what you'll do to create a website for a workshop when we're done:

1. Download the latest version of a shell script called create_workshop.sh from the Software Carpentry website and run it like this:

   $ bash create_workshop.sh github_user_name workshop_id
   

   where github_user_name could be swcarpentry, your GitHub ID, or whatever, and workshop_id is something like 2015-01-02-esu. This will create a Git repository beneath the current working directory and fill it with starter files.

2. Go into the newly-created directory named workshop_id. This will be a GitHub repository on your machine with a single branch called gh-pages containing:

   • README.md : a brief description of Software Carpentry with a prominent link to the workshop's GitHub page.
   • Makefile: contains commands for checking and building the website (see "Managing the Site" below).
   • index.html: the workshop's home page.
   • bin/check.py: a program to check the workshop's layout and the contents of its home page.
   • _layouts/workshop.html: a page template for the site.

   This repository will have a remote called origin pointing at a newly-created repository github.com/github_user_name/workshop_id. (We could get rid of _layouts/workshop.html, and put everything in index.html, but we want to make it easy for instructors to add more pages to their website.)

3. Edit the header in index.html to specify the workshop's dates, instructors, EventBrite registration key, topics, etc. (See "Required Variables" below.)

4. Make sure that index.html contains links to the lessons being taught in the workshop (see "Linking to Lessons" below).

5. Delete the installation instructions for software packages that aren't being used in the workshop (see "Software Installation Instructions" below).

6. git push origin gh-pages to publish the workshop's home page at http://github_user_name.github.io/workshop_id/.

This is all we need to do to set up a single-page site for a workshop, because:

1. We can load CSS, Javascript, and images from the Software Carpentry website.
2. We can embed setup instructions in index.html, so there's no need for _include files.
3. index.html can link to rendered online versions of the lessons and the Code of Conduct, so we don't need to include that in the workshop site every time (but see "Customizing Lessons" below).

Required Variables

index.html's YAML header must define the following variables in order for the workshop website to show up properly on the main Software Carpentry site:

• layout must be workshop (which tells Jekyll to use _layouts/workshop.html as a page template).
• venue is the name of the institution or group hosting the workshop, such as "Euphoric State University".
• address is the workshop's address, such as "Room 101, Winston Smith Memorial Union, O'Brien Street."
• country must be a hyphenated country name like 'United-States'. It is used to look up flags for display in the main web site.
• latlng is the latitude and longitude of the workshop site (so we can put a pin on our map).
• humandate is the human-friendly dates for the workshop (e.g., Jul 3-4, 2015). Please use three- or four-letter month names and abbreviations (e.g., Dec instead of December) so that columns will lay out properly on the main website.
• startdate is the workshop's starting date in YYYY-MM-DD format, e.g., 2015-07-03.
• enddate is the workshop's ending date in the same format. If your workshop is only one day long, the enddate field should be omitted.
• instructor is a comma-separated list of instructor names. This must be enclosed in square brackets, as in ["Alan Turing","Grace Hopper"]. Please do not include affiliations, links, or anything else besides the instructors' names.
• helper is a comma-separated list of helper names formatted the same way, such as ["John von Neumann"]
• contact is the contact email address to use for your workshop, such as alan@turing.edu.

The header may optionally define:

• eventbrite: a multi-digit Eventbrite registration key. If you are using Eventbrite, the admins will set this key for you. If you are using something else for registration, this field isn't needed.

Software Installation Instructions

We have tried managing software installation instructions three different ways in the last year. Several instructors found file inclusion directives and conditional blocks confusing, so we will go back to the brute force solution: the default index.html page will include setup instructions for everything, and website authors will delete the bits they don't need.

Customizing Lessons

The default index.html page contains links to our standard lessons, along with a paragraph outlining what's covered in each. As with software installation instructions, instructors can delete links and descriptions that aren't relevant to their workshop, then insert links and descriptions for custom lessons of their own.

Managing the Site

To help people manage their workshop sites, Makefile will contain these targets:

• make: without a target, this will print help.
• make commands: prints the same help.
• make check: run bin/check.py to make sure everything is formatted properly, and print error messages identifying problems if it's not.
• make site: build the workshop website locally for previewing. This assumes make check has given the site a clean bill of health, and requires Jekyll. (You can push changes to GitHub and view them there as well.)
• make listed: check that the workshop is listed on the Software Carpentry site.
• make standalone: get local copies of the CSS, Javascript, images, etc. (See "Localizing" below.)
• make page page_name.html: create a new HTML page called page_name.html (or whatever) with the right header, layout, etc. (See "Adding Content" below.)
• make permission user_name: give the user whose GitHub user ID is user_name permission to push to the GitHub repository, modify its issues, etc.
• make clean: tidy up (i.e., delete the locally-built website).

Localizing

The repository will also have a read-only Git remote called source pointing at github.com/swcarpentry/workshop_source. If people want local copies of the CSS, Javascript, and images needed to render their site (e.g., for offline work), then can pull from source. (Makefile will contain a target for this.)

Adding Content

Instructors can add their own data files, code samples, and so on to the workshop's web site simply by adding those files to the Git repo and pushing to origin. They can also run make page page_name.html to create a new page called page_name.html, then add it and push. bin/check.py and make check will check the format of these pages as well as the format of index.html.

Customizing Lessons

If instructors want to present a modified version of a lesson, or add an entirely new lesson, they will:

1. clone the lesson's repository on GitHub in the usual way;
2. modify their clone;
3. push the changes to their repository on GitHub; and
4. add a link to their workshop's site pointing at that lesson.

Instructors can add lesson material to the workshop repository, but we will encourage them to keep the lessons separate because:

1. It will keep the workshop repository small.
2. It will allow other people to use their lessons by reference (i.e., by linking to them) rather than by value (i.e., by copying the material).

Sending Fixes

The one thing this scheme doesn't have is a link between the workshop's repository and the workshop_source repository that contains the master copy of the workshop site material. This is deliberate: as per the current instructions, instructors can't just clone a website template repository on GitHub because GitHub will only let a particular user have one clone of a particular repository.

In order to send fixes to the master copy of the website template, people will therefore have to fork workshop_source, make the changes in their local copy of that, and then issue a pull request. This does mean copying changes manually from a workshop website to a local copy of workshop_source, but there doesn't seem to be any easy way around that. In practice, we expect changes to the template will be relatively infrequent, so most instructors won't ever encounter this.

Instructors and others will be able to file issues in the workshop_source repository to suggest improvements. We will also use that repository's wiki to keep track of teaching tips (just as we're using the bc repository's wiki right now).

Checklists

When create_workshop.sh creates the GitHub repository for the workshop, it will also create several issues in that repository's issue tracker to help the workshop's hosts and instructors keep track of the things they need to do, such as sending out welcome messages to learners, checking that learners will have access to WiFi, and so on. Whoever created the GitHub repository will need to run:

$ make permission user_name

for each of the other instructors to give them permission to push changes and modify issues.