For a while now I’ve been collecting snippets of code where I’ve explored concepts, played around, or generally just attempted feebly to learn something. Some of this is from before my research days and purely from a place of curiosity. During my research I stumped across Ian Bogost’s Play anything (2016). I was already exploring Bogost’s persuasive games and alien phenomenology for my research but this book in many ways changed my perspective towards many things and also structured my outlook towards research and my practice as a designer.
The full title explains this well: The pleasure of limits, the uses of boredom, and the secret of games. That as a whole sounds wonderful and through the many vignettes he paints of his experience with play he talks about how play is everywhere in the shape of playgrounds.
“Play isn’t doing what we want, but doing what we can with the materials we find along the way. And fun isn’t the experience of pleasure, but the outcome of tinkering with a small part of the world in a surprising way.” Bogost, 2016, pg3-4
A GitHub and Jekyll Playground
The collection of code snippets and curious explorations were my own little playgrounds where I enacted play as these curious rituals. So I turned to Github to craft a repository for these acts of play. But I soon faced a curious question. I wanted to be able to present my play as part of a larger playground where all could be observed. Why? I’m not really sure, but I think this is part of the play anything perspective Bogost was referring to.
I didn’t want a complicated setup and liked the simplicity and capabilities of Github Pages. This blog after all is also delivered through Github as are most of my projects and playful activities.
A clean and simple setup
I won’t go into the details of the different iterations I went through before settling with a custom Jekyll setup. There was a lot of testing and exploration with additional learning opportunities. I’m not a web developer just a tinkerer so here’s my clean and simple setup for creating a collection of curious coding playgrounds using Github and Jekyll. You can see the Github repo here but let’s start with the folder structure.
|
|
It took me a while to understand but this is essentially all there is to it, the structure is simple and easily expandable. With the settings I’m about to share a static website can be made using markdown files in Github, with additional ‘collections’ or project folders that are independent of the Jekyll site; or not if you want, that’s right, they don’t need to be independent and you can easily treat the projects as additional pages though there is an easier setup for that.
Jekyll setup step-by-step
To start we’ll prepare the index file. Since Github will use Jekyll to parse any markdown file into HTML, it simply needs some information in the YAML section of our markdown files to get started. Adding the following to the index.md will let Jekyll know it has to parse that file, naming it index is important for the static site to be registered.
|
|
For those curious the --- at the start and end of a markdown file separate it from the actual content as the YAML portion where configurations and data keys can be set. There is a list of different keys that can be called here but we can also make our own and that makes YAML very powerful. It’s essentially a way to serialise data to your liking.
Configuring the site is done using the _config.yml which needs to be in our site root. For my purposes I prepared it like so.
|
|
The most important parts are the plugins which are what we need for Jekyll to load. These plugins are enough for static site purposes, there are other plugins that can be added here for further functionality such as help with making posts or a blog.
The collections is what allows us to have our projects or playgrounds. Collections are a way to pull in the projects folder as independent pages or sites that can function on their own. Keeping the output: true is necessary here for Jekyll to actually make the pages from what I understand. The permalink lets Jekyll know how to manage the site links between collections and the main static page. This will make sense once you see the layout template we prepare. Finally, the baseurl is set as the Github repo’s name to again ensure all links start from the correct source.
The magic of metadata
This was a particular learning curve for me to understand how this metadata file could be setup. I wanted to use the YAML keys as a way to store data about projects and fetch them to the static home page, essentially listing projects out. It’s part of the collections feature of Jekyll but it’s also a clean way to have Github interact with Jekyll. Here’s an example of the metadata file for a project in the repo called EmojiDice.
|
|
The key’s like title, description, etc can be called anything since they are just data points being referenced in the home.html layout file. The url key is what’s needed to ensure the correct link is formatted. What is important to do here is to ensure the file name for this YAML metadata file is the same as the project folder. So in this case, the project folder is called emojidice and the metadata file is called emojidice.yml, Jekyll handles the rest.
Bringing it all together in our layout
Now that we have a project setup as well as its metadata, we can finally make the layout for our site. In our layout we need to be able to display our projects as that’s the whole purpose behind this curious ritual! We are already calling home.html as the layout for our index file so that’s what we have to set up in the layouts folder. The structure for this template is a basic HTML page with some Jekyll hooks to pull in dynamic data, the full file can be viewed in the repo but this portion is where the magic happens.
|
|
It’s essentially a for loop that iterates inside an unordered list. Each new list item being made has hooks in the middle such as {{ info.title }}that are fetching the unique keys we setup in our metadata file for that project. The loop knows to look at site.data.projects as in site-root/data/projects/ folder for any projects then compare them against the projects/ folder in our site root.
With that setup, all that’s left is to make it look pretty. For the design of the site I kept it all simple focusing on being just a way to represent each playground. You can find the full layout and stylsheet inlayouts/home.html and assets/style.css respectively in my playgrounds repo.
Setting up Github Pages
At this point we have the building blocks for our static custom Jekyll site but we still have to setup Github to use its Pages feature. Github Pages does all the heavy lifting for us but in order for us to use our own custom Jekyll layouts and configurations we have to tell Github not to use it’s own Jekyll configuration. The Github Pages feature defaults to using it’s own Jekyll theme and configurations, this is where we need to ensure we initiate our own Jekyll configuration. You may have noticed the Gemfile in the repository, this is where that comes in.
|
|
Jekyll is Ruby based, unlike Hugo which this blog is being powered by which is Go based. It took me a while to figure out Hugo and now looking at Ruby I’ve realised I can’t be proficient in either! That said, there are ample resources around the internet and now with ChatGPT picking up basic skills for programming languages are quite easy. I know this much that the Gemfile is necessary to initiate our Jekyll configuration. All this file is telling Github is to pull in Jekyll without any configurations such as themes etc and instead ensure the plugins we require are pulled in.
Finally, all we need to do is now upload all of this to Github and initiate Github Pages. For that we can go to the repo Settings → Pages (left menu) and selecting the branch we would like to deploy our repository from which in this case will be the main branch. And that’s it! We have a static site powered by Github Pages with a custom Jekyll static site generator that iterates over additional static sites within itself! In other words, the project folders can be independent HTML files with their own scripts, styles, and more as well as markdown files that will get parsed by Jekyll into HTML with whatever layout we would like them to follow.
Play is truly everywhere, even in the making of this collection of playgrounds through Github. I’ve learned a lot in the process of making this and hopefully more curious playgrounds full of design and code will be emerging in the days to come.