This repository is a template for creating a workshop page for eScience Center Digital Skills, and the Carpentries Software Carpentry, Data Carpentry, Library Carpentry. We are committed to offering a pleasant setup experience for our learners and organizers. If you run into problems, or would like to suggest improvements, please submit an issue or mail us.
-
Please do not fork this repository directly on GitHub. Instead, use GitHub's function to copy this template repository and customize it for your workshop. On this page (https://github.com/esciencecenter-digital-skills/workshop-template), click on the green
Use this template
button (top right). -
Select the owner for your new repository. This should be
esciencecenter-digital-skills
GitHub organisation. -
Choose a name for your workshop website repository. This name should have the form
YYYY-MM-DD-carpentry-curriculum
, e.g.,2016-12-01-ds-gpu
, whereYYYY-MM-DD
is the start date of the workshop,ds
stands for Digital Skills, andgpu
is the workshop name in this example. -
Make sure the repository is public, leave "Include all branches" unchecked (don't worry about the
gh-pages
branch, it will be created by a github action). Click on "Create repository from template". You will be redirected to your new copy of the workshop template repository. -
Go to the the workshop repository that is just created. Manually run the 'Build and deploy Jekyll site to GitHub Pages' github action. See instructions for manually triggering workflows here
-
Your new website will be rendered at
https://owner_name.github.io/YYYY-MM-DD-type-curriculum
. For example, ifesciencecenter-digital-skills
is the owner, the workshop's URL will behttps://esciencecenter-digital-skills.github.io/2021-11-02-ds-gpu/
. Please note that the github action that builds the website can take a few minutes to complete! -
Click on "Settings" tab. In the left sidebar, click on "Pages". Under "GitHub Pages", use the gh-pages branch from drop-down menu and press "save". For more information, see GitHub documentation.
-
Please do your work in the repository's
main
branch. A GitHub action is used for deployment that creates agh-pages
branch. See building a Jekyll site using a GitHub Action for more information. -
To trigger deployment of a new version of the website, create a new release of your repository
-
The file
data.csv
in_data
directory contains the workshop information. See the documention. -
The file
eventbrite.json
in_data
directory contains eventbrite code. See the documention. -
Additional lesson information lives in a folder in workshop metadata repository. See the documention.
-
In some cases you want to deviate from the default lesson information (also known as 'workshop metadata'). The steps are as follows:
- In the corresponding folder in the workshop metadata
repository
add a new file. Give it a suitable name.
For example, if you want a different schedule for your workshop create
a new file called
schedule-2.md
orschedule-in-person.md
. - Add the desired workshop information to the file and commit to the
main
branch. - In the workshop repository edit the
index.md
file. Find where the default workshop metadata markdown file that you want to replace is included. For example: the schedule.md file is included here Instead of the default file, point to your new file (i.e.schedule-in-person.md
).
- In the corresponding folder in the workshop metadata
repository
add a new file. Give it a suitable name.
For example, if you want a different schedule for your workshop create
a new file called
-
Once you commit this, the github action will rebuild the workshop website. The
index.md
file will point to the alternative workshop metadata markdown file, so that will be included in the workshop website. -
There is a
collaborative_document.md
in thefiles
directory of this repository. You can use it as a template to create a collaborative document on hackmd. Please note that you need to sign in. -
You can automatically create an exercises document. Manually run the 'Extract exercises' github action. See instructions for manually triggering workflows here This will extract all exercises from the lesson material, and put them in files/exercises-document.md If it doesn't work automatically you can also manually use the python package that extracts the exercises
If you are already familiar with Git, you can clone the lesson and workshop repositories, and edit these files. Then push your changes back to the repository. Otherwise, you can edit files using the GitHub web interface.
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 in the lesson example setup instructions. Then, you can preview your site locally with:
make serve
and go to http://0.0.0.0:4000 to preview your site. Alternatively, if you'd like to run Jekyll inside a Docker container, you may run
make docker-serve
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 given in the lesson template.
Sometimes the template is not picking up the right metadata from https://github.com/esciencecenter-digital-skills/workshop-metadata. When something goes wrong it can help to understand how this workshop template links different data sources together.
- See this line in
index.md
. In the lines following we try to find the workshop metadata url based on the curriculum and the flavor if it exists. - The flavor and curriculum are obtained from the
flavor
andcurriculum
column of_data/data.csv
. - The metadata is fetched from the metadata url
This is on purpose. We only trigger a new build upon creating a new release.