How to create a workshop webpage

Workshop Webpages

We have designed a standardized format for workshop information and materials. The workshop webpage is designed to contain all the necessary information for participants to learn more about what the workshop will involve. The webpage is very important because it is the legacy of the workshop and is what enables us to redeliver the same workshop with minimal effort, with potentially a new set of leaders and helpers. It is also an outward facing representation of the initiative and therefore sets the standard of what we want to achieve.

The audience of this webpage includes

1. Individuals interested in the workshop (who may or may not register).
2. Participants who have signed up for the workshop and want to know how to prepare their machine.
3. Individuals who want to complete the course in their own time.
4. Workshop leaders and helpers who are delivering the sessions.

Creating a new workshop

This webpage template (and the ultimate workshop webpage) are built using Jekyll. To contribute to workshop development you will need a GitHub account and to be a member of the University of Exeter RSE Group organization (UniExeterRSE). The template is available as a repository and each workshop will require it's own repository that is generated from this template. To create a new workshop you need to select the green "Use this template"

This will launch a page where you can provide some of the initial details for the repository. Specifically you need to

• Check that the Owner is set to UniExeterRSE
• Provide a name for the workshop. Please using lowercase letters only and "-" instead of spaces (e.g. intro-to-r).
• Select "Public"

You can then click the green "Create Repository" button at the bottom.

Publishing the webpage

In order to make the webpage visible you need to tell GitHub which branch the webpage is located at. This can be changed in Settings, which can be selected as the option on the far right in the navigation menu towards the top of the page (see orange arrow below). Within Settings you need to navigate to the Pages tab, which is listed in the sidebar on the right as the last item under Code and Automation (see blue arrow below).

If your page is published there will be a box, near the top, which displays the web address, an example of which is shown below.

If no such box is visible, then the Source is probably set to None. From the drop down menu select main branch and click save. The box should now appear.

Workshop webpage address

The webpage can then be found at the following address: https://uniexeterrse.github.io/repository-name

Configuring site wide settings

There are some elements of the web page that are repeated on every page, such as the workshop title. These can be define globally in the _config.yml file. Specifically all the variables listed under # Basic options need to be completed.

Editing the workshop home page

The content of the workshop home page can be edited in the index.md file in the main repository folder. This can be edited directly on GitHub by clicking filename and then once the file in open, you can click the little pencil symbol in the top right corner of the file, to open edit mode. Alternatively you can clone the repository onto your computer and edit in a text editor of your choice. A review of markdown text editors can be found here.

The sections which need to be completed include:

• Overview a short paragraph describing the concept of the workshop and who it is targeted at.
• At the end of this workshop you will be able to Provide a bullet point list of a handful Intended Learning Objective. Guidance on vocabulary for these can be found here.
• Pre-requisite knowledge Detail knowledge that will be built on in this workshop. Ideally in the form of a workshop we offer or a list of skills. If this is a beginners workshop this should be None or minimal.
• Workshop Format Complete the number of sessions the workshop will consist of. You also need to edit the address of the schedule page, by replacing "UoE-workshop-template" with your repository name.
• Upcoming course dates If known add the date and location of the next workshop.
• Set-up instructions for attendees The set up instructions are located on a separate page which is linked to from the home page. Here you just need to change the webpage address by replacing "UoE-workshop-template" with your repository name.
• Start course This is a link to the course notes again you need to edit the link, by replacing "UoE-workshop-template" with your repository name.
• Follow up courses Complete if appropriate.
• Feedback Check if there is a link to the feedback survey and if not please add.
• Acknowledgements There is a separate page which lists all individuals who contributed to the development of the course. In this section please mention any resources that you used as the basis of the materials.

Adding Workshop Content

Each workshop is organised into a series of sessions run on consecutive weeks. Each session is made up of a number of lessons or episodes. As a rough guide an episodes should last between 20-90 mins. The course content is built from these episodes, where each episode is a page. The episodes are numbered and are then dynamic stitched together in order. By specifying the length of each episode a schedule for the workshop is also automatically introduced. The course notes (i.e. episodes) are stored in the _episodes folder. You will see a series of files, including 01_intro.md. The first episode for each workshop is an Introduction. There are some core elements that will be included in the Introduction for all workshops, which are already in this file, but if you need to add some specifics then please add them to this file.

The filename for all episodes is the format XX_name.md where XX is a two digit number used to document the order of the lessons and the name, something to easily identify the content of each episode. As well as the Introduction episode, you have the file for the second episode already provided. Change the filename to something more useful, but keep the 02_. You can then add the content to this file as required.

To add new pages, create a new file in this folder, you will need to include the following at the top of each file.

---
layout: page
title: Introduction to ...
order: 2
session: 1
length: 20
toc: true
--- 

Within this YAML header you need to edit

• title change to a short title that will be displayed at the top of the page and in the schedule
• order change number to reflect where in the episode order this episode occurs
• session change number to reflect which session this episode occurs in
• length change number to reflect length (in minutes) of this episode

Underneath the --- you can add your content in markdown.

Resources Page

Set up Page

Acknowledgements Page

The page can be editted by editting the content of the acknowledgements.md file.

Further technical details

The webpage is build using a combination of Jekyll, markdown and liquid. Jeykll expects some YAML front block to specify what to do with the page and what it should look like. It takes advantage of prescribed layouts for different pages. The front block can also contain variables which are used to dynamically create content.

Page types

There are three different standardized layouts available

1. **home ** This is for the workshop home page and contains all the important information for the course as well as links to other pages. It serves as a resource for individuals interested in the workshop and those signed up to attend.
2. **page ** This is for workshop content, where multiple pages are linked together in a specific order to build a workshop
3. **info_page ** This is for supporting information that can be linked to from the home page.