Skip to main content Link Menu Expand (external link) Left Arrow Right Arrow Document Search Copy Copied

How to Create a Workshop Site!

Follow these steps to create a new workshop website from this template repository.

For further documentation, see: Learning Modules Documentation and Thoughts.

Table of Contents

0. Example Workshop Website

Example workshop website

Example workshop website repository

1. Create a new repository using this template

  1. Navigate to the SCDS template repository
  2. At the top right, click Use this template > Create New Repository
  3. Select scds as the repository owner
  4. Give the new repository a name (we try to keep it to a few words and use hyphens to delimit words–e.g. intro-voyant)
    • Set the description to: Repository for workshop website: WORKSHOP NAME
  5. Set the repository visibility to Public
  6. Click Create repository from template
    • Full instructions (from GitHub) here.

2. Configure GitHub Pages

  1. In the new repository, go to Settings
  2. On the left hand side, select Pages (it should be near the end of the Code and automation category)
  3. Under Build and deployment, switch the None branch to main/master
  4. Click save. The URL to your new website will be displayed. It will take the form https://scds.github.io/<repository_name>, where <repository_name> is the name you created in step 4 of the previous section.

3. Set up Google Analytics

  1. Go to the admin page for the SCDS workshop pages
    • If you do not have access, let Jay know. Skip this step for now and come back to it when possible.
  2. Click Data Streams
  3. Click Add Stream > Web
  4. Enter the GitHub Pages URL created in previous section (i.e. https://scds.github.io/<repository_name>). Provide a name.

4. Edit the README file

  1. Enter the workshop name, workshop URL, and contributor name(s) where prompted
  2. Remove the << >>

5. Add necessary documents, images, and data

assets/docs/

  • Add any PDFs (slides, worksheets, etc.) that you will either embed or link to in the main text.

assets/img/

  • Add any workshop-specific image(s), including the title image and any images to be shown in the main content.

data/

  • Add any datasets or other files that are required for the workshop.

6. Edit the config.yml file

Comments

Everything after a # is a comment. Comments are ignored by the website.
To uncomment a line, remove the # at the start.
To comment a line, add a # at the start.

  1. Update/verify lines above “Edit Above” text. Put text in double quotes. These include the following variables:
    • title - workshop title
      • If the workshop title is long, try to shorten it. Use acronyms or exclude parts of the title.
      • Try to keep it shorter than “GitHub and GitHub Pages”.
    • github_repo_url - GitHub Pages URL from Section 2
    • gh_edit_repository - GitHub repository URL from Section 1
    • ga_tracking - Measurement ID from Google Analytics from Section 3
    • credits - the line of text in the footer
      • If left unchanged, it will read Module content created by the <a href="https://www.scds.ca">Sherman Centre for Digital Scholarship</a>.
      • Try to roughly follow the format of Module content created by <a href="LINK HERE">NAME</a> and <a href="LINK HERE">NAME</a>; edited for online use and online pages created by <a href="LINK HERE">NAME</a>.
        • Use the <a href="LINK HERE"> if you’d like to link to a personal site or research profile. If you don’t have a website to link, remove the <a href...> and </a> tags and just keep your NAME. Example shown below.
        • Module content created by NAME and NAME; edited for online use and online pages created by NAME.

    Example

    title: GitHub and GitHub Pages # Enter workshop title here  
github_repo_url: "https://scds.github.io/github-pages/" # Enter workshop URL (in github pages) here  
gh_edit_repository: "https://github.com/scds/github-pages" # Enter the github URL for your repo  
ga_tracking: G-F9JFEFZ01G # This needs to be set up in Google Analytics once you know the website URL (ask Jay to do this). Then the tracking code needs to be taken from Google Analytics and pasted here.  

# This line appears in the footer. Use it to credit the people who created the workshop content, and those who set up the online pages. 
# If you know some HTML, you can use HTML tags.
# To create a link: <a href="PUT URL HERE">the text you want to show up</a>
# Template: 'Module content created by <a href="LINK HERE">NAME</a> and <a href="LINK HERE">NAME</a>; edited for online use and online pages created by <a href="LINK HERE">NAME</a>.'
credits: 'Module content created by the <a href="https://www.scds.ca">Sherman Centre for Digital Scholarship</a>.'
  2. Series specific settings
    • DMDS - The SCDS template should already have these settings. An example is included below.

    Example

    # DMDS Settings
subtitle: "This workshop is part of the SCDS Do More with Digital Scholarship series."
nav_footer_logo_bottom: "https://raw.githubusercontent.com/scds/jtd-mcmaster/main/assets/images/scds-logo.png"
nav_footer_logo_bottom_href: "https://scds.ca/"
nav_footer_logo_top: ""
nav_footer_logo_top_href: ""
    • DASH - Comment out the lines under DMDS (add a # symbol at the start of each line), and uncomment the lines under DASH (remove the # symbol at the start of each line).

    Example

    # DASH Settings
subtitle: 'This workshop is part of the Data Analysis Support Hub series.'
nav_footer_logo_bottom: "https://raw.githubusercontent.com/scds/jtd-mcmaster/main/assets/images/scds-logo.png"
nav_footer_logo_bottom_href: "https://scds.ca/"
nav_footer_logo_top: "https://raw.githubusercontent.com/scds/jtd-mcmaster/main/assets/images/dash-logo.png"
nav_footer_logo_top_href: "https://library.mcmaster.ca/services/dash"
    • Other/Custom - Want to make a module that isn’t part of DMDS or DASH? Comment out the lines under DMDS (add a # symbol at the start of each line), and uncomment the lines under OTHER (remove the # symbol at the start of each line).
      • nav_footer_logo_bottom: Replace this with your series logo link. Leaving it as “” will show no logo.
      • nav_footer_logo_bottom_href: If your series has a dedicated website, put your website link here. This will let users click on the image to go to your website.
      • nav_footer_logo_top: An optional, secondary logo.
      • nav_footer_logo_top_ref: Link address for your secondary logo.
      • subtitle: A short line attributing the workshop to your series. This appears in the footer of all pages.

7. Add content to workshop pages

There are two places to find content.

Root directory

This is the top page of your GitHub Repository. It contains most of the template pages.

index.md

  • This is the home page of your site.
  • Edit all the blanks, which include:
    • the page header
    • the link to the title image
    • the brief description of the workshop
    • the prerequisites (if any)
    • the learning objectives
    • the duration (if possible)

previousOffering.md

  • Does your workshop have a live recording you’d still like to feature? This is just the page for that!
  • You can include any slides or workshop videos here, alongside the month/year they were used in.
  • If you’re not using this file, delete previousOffering.md. Also, go to index.md and set has_children at the top to false too.

preparation.md

  • Some workshops may need attendees to install software, create accounts, or download files before attending/starting the workshop. This is where you outline the requirements and/or steps for any preparation needed prior to the workshop. If there is nothing to prepare, mention it on the page.
  • Edit:
    • are there any accounts needed?
    • are there any files needed?
    • are there any software applications needed?

introduction.md

  • Some workshops may have an introduction to the content before diving in. This is where you’ll put it.
  • Since not all workshops need this page, feel free to remove it.
  • Edit:
    • the page header
    • the introductory paragraph
    • video iframe (if applicable)
    • slides/content iframe/links (if applicable)
    • text version (if applicable)

lessonsPage.md / workshopRecording.md

  • If your workshop has lessons, delete _workshopRecording.md. Leave lessonPage.md the way it is.
    • If you want to include content in lessonsPage.md rather than leaving it as a folder, set blank to true in the front matter at the top.
  • If your workshop has a singular recording/slides, rename _workshopRecording.md to workshopRecording.md and delete lessonsPage.md. Also delete the lessons/ folder.
    • Edit the link for workshop recording and slides. Remove/add other content as you need.

conclusion.md

  • This is where you wrap up the workshop. Remind the attendees what they did/learned, any key points to remember, and point them to additional resources.
  • Edit:
    • the learning objectives
    • the additional resources

Lessons Directory

If you only have a workshop recording and haven’t already, delete the lessons/ folder and skip this step.

This is where any lessons you create go.

Make sure all the lessons are ordered right and set parent to “Lessons”.

There are already a couple premade lesson pages, including a lesson page with sublesson pages. Use these as examples. Duplicate/delete lessons as you see fit.

Edit:

  • the brief description
  • the learning objectives
  • the lesson video (if applicable)
  • the lesson slides/resources (if applicable)
  • the text (if applicable)
  • the keypoints/summary
  • the additional resources (if applicable)

8. Final Check and Touchups

  • Go to the ‘reload-modules’ repository (https://github.com/scds/reload-modules/tree/main).
    • Add your new module to the ‘modules.txt’ file. The README has instructions on how to do this in the “Adding Modules to the Module List” section.
  • Make sure all the previous/next page buttons work!
    • If they’re broken, double check the nav_order. Avoid using the same number for two pages.
    • Children pages start back at 1.
    • Tip: If you need to add a new page between 1 and 2, you can use decimals (like 1.5).
    • Tip: If you want to sort pages by date, use the date as your nav_order.
      • September 1st, 2020 at 1:30PM could be represented as 2020.09011330… (2020/09/01 13:30)

Example

  • 1
  • 1.5
  • 2
    • 1
    • 2
    • 3
      • 1
      • 2
    • 4
  • 3
  • Delete the kitchen_sink_DELETE.md, common_elements_DELETE.md, and how_to_create_a_site_DELETE.md files.
    • Delete _workshopRecording.md if you didn’t use it.
    • Delete lessonsPage.md and lessons/ if you didn’t use them.
  • Delete any pages, images, and files you didn’t use.
  • Don’t forget to set up Google Analytics.

Congratulations!

Your website should be up and ready to be used 😊.