Skip to content

A Gatsby theme for building workshops and tutorials on whatever topic you want

Notifications You must be signed in to change notification settings

patricoferris/gatsby-theme-workshops

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

19 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Gatsby Theme Workshops


Demo Site

A brief history

Welcome to a Gatsby Theme for building lessons, workshops, tutorials and much more. This project started from the want to shift a current project the site for Cambridge University's Tech Society's currently written in Swift, to something a bit more manageable and friendly to beginners whilst not sacrificing on capabilities, extensibility, performance and usability. Gatsby and their new Themes feature seemed like the perfect fit for turning our site into a blazingly fast one whilst also benefiting from the great community and developer ecosystem that comes with Gatsby.

Why change?

For the longest time our workshops have been written using markdown and then parsed to HTML using a custom Swift backend developed by our own people (for info see this article). This is great and worked really well but it has three main problems for us:

  1. Nobody else can use it
  2. New-joiners to the project find onboarding hard
  3. Extending the functionality was difficult

The idea was to move our project away from this structure and use a more familiar stack with Javascript or Python - then Gatsby announced the stable release of themes and it seemed perfect. It solves all of our problems allowing us to share our resources with whoever wants to easily integrate them into their codebase.

Workshop Structure

The basic, obligatory structure of a workshop is the following:

> workshops 
  > workshop-default
    > metadata.yaml
    > notes.md
    > images
      > bg.png
      > fg.png

The yaml file is for storing the metadata about your workshop and needs the following structure:

title: My Default Workshop

contributors:
  - Patrick Ferris

tags:
  - Deep Learning
  - Machine Learning
  - Neural Networks

sections: 
  - Prerequisites
  - Setup
  - Notes

The tags are particularly useful as the theme uses react-semantic-ui to add filtering by tag to your workshops from the very start.

Each markdown file represents a section of your workshop and the only requirement on these files is that they have a frontmatter (a small yaml section at the top of the file) with a title - for example:

---
title: "Main Content"
---

This workshop aims to **help** you understand...

And lastly the images folder - this is used to hold two key images (you can add others and link it in your markdown like so: ![My Lovely Image](images/my_lovely_image.png)) the background (bg.png) and foreground (fg.png) for the cover image on the workshop. Why two? The idea is that it will make it easier to display on screens of varying aspect ratios by expanding the background when whilst keeping the foreground one centred.

Configurations

Of course this seems quite limiting - here are the current supported ways for you to make it your own. When you resolve the plugin in your gatsby-config.js file you can pass the following options:

options: {
  workshopFolder: 'workshops', // Name of your folder for them (ab)
  basePath: '/workshops', // The base path for your workshop content i.e. www.my-site.com<basePath>/workshop-1
  sections: ['notes', 'setup', 'advanced'] // The different markdown files (sections) you'll want in your workshops 
}

Installation

To use the Gatsby Theme with your project, in your empty root directory run yarn add react react-dom gatsby @patricoferris/gatsby-theme-workshops

Add a new file called gastby-config.js with the following contents:

module.exports = {
  siteMetadata: {
    title: `Computer Science Workshops`, // Your site title
    description: `A cool website for computer science related workshops` // A short description
  },
  plugin: [
    {
      resolve: `@patricoferris/gatsby-theme-workshops`,
      options: {
        // You can add the options as specified above
        workshopFolder: 'workshops', // Name of your folder for them (ab)
        basePath: '/workshops', // The base path for your workshop content i.e. www.my-site.com<basePath>/workshop-1
        sections: ['Setup', 'Prerequisites', 'Notes'] // The sections you want your workshops to have
      }
    }
  ]
}

Next run yarn gatsby develop. This should create your first default workshop with some simple images and content so you can get a feel for how to lay out your amazing workshops. Now go and create!

What does it look like?

Check out the live demo of a site using the theme and hopefully in the near future the Hackers at Cambridge site will migrate to using this theme.

Want more things?

Feature requests and bugs can be brought up in the issues on GitHub, here are some of the things I'm already thinking of adding:

  • JSON Questions and Answers for the bottom of the workshop
  • Further improvements to maintaining accessibility to the workshops
  • Greater customisability through the options

About

A Gatsby theme for building workshops and tutorials on whatever topic you want

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published