README.md

training-template

This repository is The Carpentries' template for creating websites for Instructor Training workshops.

1. Please do not fork this repository directly on GitHub. Instead, please use the instructions below to copy this training-template repository and customize it for your workshop.

2. Customise the values in _config.yml and the header of index.md (or index.md.cldt for Collaborative Lesson Development Training) to configure the website for your training event. Please do your work in your repository's gh-pages branch, since that is what is automatically published as a website by GitHub.

3. (Collaborative Lesson Development Training events only) Rename index.md.cldt to index.md (replacing the original index.md) to use this file as the source of the training event page.

4. Once you are done, please send your repository's URL to The Carpentries contact]. For an Instructor Training event send the URL to [email protected]. For Collaborative Lesson Development Training, send to [email protected].

If you run into problems, or have ideas about how to make this process simpler, please get in touch. The section on customizing your website, and the FAQ and design notes from the related template for workshop websites have more detail on what we do and why.

Creating a Repository

1. Log in to GitHub. (If you do not have an account, you can quickly create one for free.) You must be logged in for the remaining steps to work.

2. On this page (https://github.com/carpentries/training-template), click on the green "Use this template" button (top right)

   

3. Select the owner for your new repository. (This will probably be you, but may instead be an organization you belong to.)

4. Choose a name for your workshop website repository. For Instructor Training, this name should have the form YYYY-MM-DD-ttt-site, e.g., 2016-12-01-ttt-oomza, where YYYY-MM-DD is the start date of the training. For Collaborative Lesson Development Training, the name should have the form YYYY-MM-DD-cldt-partN-site, where YYYY-MM-DD is the start date of the training and N is a number indicating the part of the training (1 or 2) that will be taught at this event.   For online workshops, choose online as site. In most cases, the Instructor Training Team will tell you the name of the repository you should use.

5. Make sure the repository is public, leave "Include all branches" unchecked, and click on "Create repository from template". You will be redirected to your new copy of the workshop template respository.

6. With a repository called YYYY-MM-DD-ttt-site, your new website will be rendered at https://your_username.github.io/YYYY-MM-DD-ttt-site.

Customizing Your Website

(For Collaborative Lesson Development Training, follow the steps described here but modify the index.md.cldt file instead.)

1. Go into your newly-created repository, which will be at https://github.com/your_username/YYYY-MM-DD-ttt-site. For example, if your username is gvwilson, the repository's URL will be https://github.com/gvwilson/2016-12-01-ttt-oomza.

2. Ensure you are on the gh-pages branch by clicking on the branch under the drop down in the menu bar (see the note below):

   

3. Edit the header of index.md to customize the list of instructors, workshop venue, etc. You can do this in the browser by clicking on it in the file view on GitHub and then selecting the pencil icon in the menu bar:

   

   Editing hints are embedded in index.md, and full instructions are in the customization instructions.

4. Alternatively, if you are already familiar with Git, you can clone the repository to your desktop, and edit index.md there, and push your changes back to the repository.

   git clone https://github.com/your_username/YYYY-MM-DD-ttt-site
   

   You should specify -b gh-pages to checkout the gh-pages branch because the imported repository doesn't have a master branch.

   In order to view your changes once you are done editing, you must push to your GitHub repository:

   git push origin gh-pages
   

5. (Collaborative Lesson Development Training events only) Rename index.md.cldt to index.md (replacing the original index.md) to use this file as the source of the training event page. If you are working locally, this can be achieved with the command git mv index.md.cldt index.md.

6. When you are done editing, go to the GitHub Pages URL for your workshop and preview your changes. In the example above, this is https://gvwilson.github.io/2016-12-01-ttt-oomza. The finished page should look something like this.

7. Optional: you can now change the README.md file in your website's repository, which contains these instructions, so that it contains a short description of your workshop and a link to the training website.

8. Optional: Add a link to your workshop website on the repository main page in the description/website section (look for the Edit button on the right to add).

Note: please do all of your work in your repository's gh-pages branch, since GitHub automatically publishes that as a website.

(Optional) Checking Your Changes Locally

If you want to preview your changes on your own machine before publishing them on GitHub, you can do so as described below.

1. Install the software described below. This may require some work, so feel free to preview by pushing to the website.

2. Run the command

   make serve
   

   and go to http://0.0.0.0:4000 to preview your site. You can also run this command by typing make serve (if you have Make installed).

3. Run the command

   make workshop-check
   

   to check for a few common errors in your workshop's home page. (You must have Python 3 installed to do this.)

(Optional) Linking to Your Page

At the top of your repository on GitHub you'll see

No description, website, or topics provided. — Edit

Click 'Edit' and add:

1. A very brief description of your workshop in the "Description" box (e.g., "Oomza University workshop, Dec. 2016")

2. The URL for your workshop in the "Website" box (e.g., https://gvwilson.github.io/2016-12-01-ttt-oomza)

This will help people find your website if they come to your repository's home page.

Creating Extra Pages

In rare cases, you may want to add extra pages to your workshop website. You can do this by putting either Markdown or HTML pages in the website's root directory and styling them according to the instructions give in the lesson template. If you do this, you must also edit _config.yml to set these three values:

1. carpentry is "cp" (for The Carpentries). This determines which logo is loaded.

2. title is the title of your workshop (typically the venue and date).

Note: carpentry and email duplicate information that's in index.md, but there is no way to avoid this without requiring people to edit both files in the usual case where no extra pages are created.

Installing Software

If you want to set up Jekyll so that you can preview changes on your own machine before pushing them to GitHub, you must install the software described below. (Note: Julian Thilo has written instructions for installing Jekyll on Windows.)

1. Ruby. This is included with Linux and macOS; the simplest option on Windows is to use RubyInstaller. You can test your installation by running ruby --version. For more information, see the Ruby installation guidelines.

2. RubyGems (the package manager for Ruby). You can test your installation by running gem --version.

3. Jekyll. You can install this by running gem install jekyll.

You can check the formatting of your header by running bin/workshop_check.py (which is invoked by make workshop-check). You must have Python 3 installed in order to do this, and you will also need the PyYAML module.

Getting and Giving Help

We are committed to offering a pleasant setup experience for our learners, Trainers, Instructors and workshop hosts. If you find bugs in our instructions, or would like to suggest improvements, please file an issue or mail us.