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:

Slug Validation

For workshops teaching a core or mix and match curriculum, i.e. where carpentry is set to swc, dc, or lc, the website build will check that your repository name matches the Carpentries slug format - YYYY-MM-DD-site[-online], e.g. 2024-05-07-oomza-online.

If your repository name does not match this format, the build will fail, and will direct you to rename your workshop website repository to a valid slug. You will then need to commit a change to the repo to rebuild the site, e.g. adding a space or other inconsequential change to the README.md.

Workshop websites using cp or incubator will go through the same check, but the build will not fail if the repo name does not match the slug format. You will see a warning in the build output instead.

Incubator lessons

For workshops teaching lessons in The Carpentries Incubator, i.e. where carpentry is set to incubator, you should uncomment the following three fields in _config.yml:

Site URL

GitHub Pages sites are formatted as https://GITHUB_USERNAME.github.io/REPOSITORY_NAME. For example, if the URL for your repository is https://github.com/gvwilson/2015-07-01-oomza, the URL for its website will be http://gvwilson.github.io/2015-07-01-oomza.

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 online workshops 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

By default, the template displays the typical schedule for your workshop based on the values of the variables set in the _config.yml. If you need to make minor modifications to this schedule, you can edit the schedule.html file found in the sub-folder of the _includes folder that matches the type of workshop you will be teaching (dc, lc, or swc).

If you wish to create your own custom schedule, an empty template is available in _includes/custom-schedule.html. In this file, we provide the structure for a 4-day workshop as it is often used for online workshops. To use this custom schedule instead of the one provided by default in the template, delete the block of code found under the “Schedule” header in the index.md file and replace it with{% include custom-schedule.html %}.

The schedule is formatted using a table. If you would like to learn more about how to write tables in HTML, here is an HTML table overview from Mozilla and the HTML tables chapter from w3schools.

For pilot workshops, some placeholder text including a link to the lesson homepage will be displayed instead of a schedule table. The lesson homepage will contain estimated timings for teaching the lesson. Use the approach described above for _includes/custom-schedule.html if you would like to create a schedule table to replace this text.

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