Customizing Your Workshop's Website

Table of Content

Configuration File _config.yml

You should edit the _config.yml configuration file in the root directory of your workshop to configure some site-wide variables and make the site function correctly:

For example, if the URL for the repository is https://github.com/gvwilson/2015-07-01-miskatonic, the URL for the website will be http://gvwilson.github.io/2015-07-01-miskatonic.

You should not need to modify any of the other variable values in _config.yml.

Home Page (index.md): data in the YAML header

Your workshop’s home page lives in index.md, which must define the values below in its header. If your workshop is taught online, see the following section for customization options.

The header may optionally define the following:

For online workshops

If the workshop is online, follow the same instructions as above with the following modifications:

By default, the Setup Instructions will list the installation instructions for the videoconferencing service Zoom. If you use a different videoconferencing service, you can edit the file in _includes/install_instructions/videoconferencing.html to include the relevant installation instructions.

Home Page: Schedule and Syllabus

To edit the sections titled Schedule and Syllabus that appear on the website so that they show what you are actually planning to teach and when, you need to modify the files that are located in the appropriate workshop folder (dc, lc or swc) inside the _includes folder.

Home Page: Setup Instructions

If you need assistance with customizing the setup instructions for your website, feel free to ask your questions in the Carpentries Instructors Slack channel (join The Carpentries Slack workspace).

Software Carpentry workshops

Default settings

For Software Carpentry workshops, setting the flavor variable in _config.yml to r or python will include the respective installation instructions for these tools. Additionally, by default, the installation instructions for a text editor, the Bash shell, and Git are included.

If you need to remove tools

If you need to remove any of the instructions for the default set of tools, you can delete lines that include these instructions in the _includes/swc/setup.html file.

If you need to add tools

If you need to add installation instructions for other tools, we provide installation instructions for SQL and OpenRefine. To make them appear on your workshop website, you can move the {% include %} statements outside the comment block in _includes/swc/setup.html.

If you need to add installation instructions for other tools, you will need to write your own. You can use installation instructions for other tools located in the _includes/install_instructions/ folder as examples.

Data Carpentry workshops

For Data Carpentry workshops, installation instructions live on the workshop overview page for each curriculum. Instead of including installation instructions in the workshop template, the workshop template includes links to these instructions. The correct link will be displyed when using the appropriate combination of values for the curriculum and flavor variables in the _config.yml file.

Library Carpentry workshops

By default, Library Carpentry workshop websites include installation instructions for the Bash shell and Git.

You may need to add installation instructions for additional tools you will be using during your workshop by editing the _includes/lc/setup.html file. You can either write your own instructions using the ones provided in _includes/lc/setup.html as an example, or, if you are using tools that already have installation instructions provided for Software Carpentry, you can add {% include install_instructions/<filename.html> %} where <filename.html> needs to be replaced by one of the files in the _includes/install_instructions folder.

Homepage: who can attend?

If you want to specify who can attend the workshop you are advertising, there is a commented-out section in index.md that you can use to inform workshop website visitors of who can attend the event. You may want to specify that only members of your university, department, etc. can attend or that the event is open to the public. We don’t provide templated text for this as each situation is different. We do provide a section, called “Who can attend?” for you to specify this information.

To use it, move the {% endcomment %} line above the <p> tag marking the beginning of this section and edit the paragraph to reflect the attendance policy for your workshop.

Updating the repository

If for some reason, such as the installation instructions having become disconnected with the current lesson material, you need to get changes from this repository into the clone of it with your workshop page, please follow the steps bellow:

  1. Add the workshop-template repository as upstream:
     $ git remote add upstream https://github.com/carpentries/workshop-template.git
    
  2. Fetch the data from upstream repository (also know as the workshop-template repository):
     $ git pull upstream
    
  3. Address possible merge conflicts, and
     $ git commit -a
    
  4. Push the changes to your repository on GitHub:
     $ git push origin gh-pages