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.
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:
- Nobody else can use it
- New-joiners to the project find onboarding hard
- 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.
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.
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
}
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!
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.
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