Netlify CMS and Jekyll

This post is made up of messages I sent in the Radical Directory Discord, trying to explain the tech to the other collective members

so I did a bunch of research into the platform which I think would, at this point, be the easiest to use to get a functional website set up. when we had the meeting on zoom, i assumed that it would be hard to get the core functionality of the website - the calendar and the directory - working in an effective way. after a bit of research, i think it is not going to be that hard after all and can be implemented on the platform that I was proposing to make a simple site on - Github Pages using Jekyll as a Static Site Generator. since I am pretty sure that using Jekyll we can make a functional, adaptable website, I think ultimately it will be easier to start with Github Pages from the get go rather than potentially building a landing page on Wix as a trial. I am feeling excited and motivated, I have a fair bit of capacity I think and if it's ok with others, I feel happy to lead the more technical/code specific parts of this process of getting the site up and running. I also feel very much able to outline and open that process up so that anyone else can be as involved as they want, which would be really great! to that end i'll try and outline my proposal below in more detail

Github is a website where people can put files online as part of a project. As well as hosting the files, it provides an interface to interact with the files using 'git', which is software that enables 'version control'. Version control is about keeping track of different versions of a project, and helps prevent conflicts when different people work on things at the same time. It tracks every change that is made, so if something goes wrong, it's easy to go back to an earlier version. It's kind of like Google Docs or Google Drive, except that you can't edit the same document simultaneously in real time and see each others changes. On the plus side, it is really good at tracking the way entire folders are changed with multiple interacting files. It is not difficult to use but definitely has a little bit of jargon that might take a sec to wrap your head around. There are helpful videos on youtube with quick explanations of the github language, and there is also a longer series of videos called 'github for poets' which is a cute and funny as well as pretty in depth overview. Github ALSO have a service where the files that they host as part of a project can be automatically hosted as a website. It's called Github Pages. It's free for non commercial projects. Lots of things are hosted on Github Pages. They give you a free web address (domain name, or in this case, subdomain) at yourproject.github.io, which anyone can access. So really easy free way to go public. We can also buy a custom domain name but still use Github Pages as host. (hosting is usually the most expensive part of having a website, more than the domain name, so this is good!)

Github Pages is set up to work with something called Jekyll. Jekyll is a 'static site generator' (SSG) which basically means that it takes a bunch of files, like ingredients, it runs a bit of code to transform them, like cooking, into the different files that make up a real actual 'static' website, like a delicious meal. In the process, it formats everything and combines it all in a way that would be really hard to do manually. For example, if we had a cute slogan at the top of every page, and you wanted to change the manually, you would have to go into every single HTML file and edit the code in each one in exactly the same way. with Jekyll, the HTML code for the top of the page, including the slogan, is kept in one place, and the content of the pages is kept in a different place, and the footer is in another place. When it generates the actual pages, it goes to each separate ingredient file and combines them for you in a way that looks nice, because the formatting information is kept in a different place. that's how Jekyll works.

A static site is one where, once it's generated, it doesn't have to change. Static sites are not 'interactive' - they don't by themselves generate content in reaction to people visiting the site. Once it's generated, all the different files that make up the site stay the same until a new version is generated. That said, they can still do a lot of stuff - cool visual things that move, forms that save data, etc. That stuff happens through 'client side scripting' - usually Javascript. What static sites can't do is server side scripting. That's when you need a dynamic site. Dynamic sites require a server, like, a computer, to be constantly running, and they usually have databases stored in a way where the server code can manipulate it in real time. The difference is a little bit confusing and I'm still fully wrapping my head around it BUT it's important because Github Pages will only allow us to have a static site.

so with Jekyll, it's built so it can run as a blog. The idea is that you have text files, which are kept in a certain folder, and each text file is a blog post. You just need to put a bit of particular info at the start of each file, formatted in a particular way, so that Jekyll knows what to do with it. there's also ways to put formatting on the content of the blog post, so you can have headers, bold, italics, links, images etc. You just have to put certain characters to tell it to do the formatting. That text formatting is called 'Markdown' and it's really easy to learn. then when you generate the website, it takes all the text files and processes them and orders them by date and time in a list, and that's how it makes the blog.

That's a little example of markdown. the different colours and italics etc on the left are not actually in the text - it's just a text file but whatever app they are using is colouring the code to make it easier for the person writing it

So the difference between this and something like Wordpress is that with Wordpress, you don't have to manually create text files - you have an online interface which allows you to put in the content and see how it will be formatted in real time. that feature of wordpress is called its Content Management System or CMS.

The reason i'm talking about blogs is that they work similarly to how directories and calendars work. Blogs, directories and calendars all collate lots of individual packets of information. The main difference is the way that they organise them. And unlike other preexisting blog platforms like Wordpress, Squarespace or Wix, coding our own website using Jekyll will allow us to use our little packets of data (whether it's a blog post, an entry to the directory, or a description/invitation to an upcoming event) in any way that we want.

For illustration, this is what a blog post looks like in Jekyll. The stuff at the top, between the lines with three dashes, is where the information ~about~ the blog post is kept, like the title. Tags and categories also go there.

so the types of information put into these headers can be set arbitrarily, which is useful, because then you can set code in the layout pages that refers to a certain category of information. so for example if categories and tags didn't work for our directory, then we could organise the listings a different way. like I was saying in the video chat, the way that we organise data about activist orgs seems pretty important and could have interpersonal and political implications, so it feels important to me that we can arbitrarily change the way it is organised. so when I was talking about little packets of information, like blog posts, directory listings, events, etc, the word Jekyll uses to talk about that is 'collections'. Since it's built with blogs in mind to be particularly easy, it comes installed with a preexisting collection called 'posts' and has certain settings built in for interpreting them in a way that makes sense for blogging. While I know we talked about action reports, I think there is still a bit to be fleshed out about exactly what that would look like and whether it would fit well into that 'blog' format, but either way that's probably a good thing to know.

So obviously the major drawback to this entire approach is that in order to make changes to the website, somebody has to change certain text files in line with the correct formatting, upload them to Github, and then the Jekyll site needs to be generated. Now in terms of basic use of Jekyll, github can handle the generating part by itself, but my understanding is that when we want to do more complex things such as using non-approved plugins, then we will have to generate the site manually and upload the contents. This isn't hard per se, but the way you do it is in the shell terminal on your computer, and you have to have all the relevant software installed on your computer. This is actually the reason I've been holding off from making a start on any of this - my computer is currently at the repair shop. I should be getting it back tomorrow, so I can do things then. But the point is that it's a bit of a bottleneck which is not ideal for a site that needs to be changed and updated by multiple people, and potentially changes will have to be made quite quickly, especially for events that get cancelled etc. BUT I think I have a solution. So earlier I mentioned that the difference between Wordpress and a Jekyll blog is that Wordpress has a CMS feature. Actually, it's possible to get CMS on Jekyll too! There are a few options, most of them are paid services, but I think the best is this one which is actually open source, free and has instructions how to install it on Jekyll: https://www.netlifycms.org/

Once there is a CMS installed, anyone on the Radical Directory team can just like on wordpress, go to an 'admin' page and log in, then add, edit or delete listings from the calendar, directory or blog if we make one. what I'm not sure about is whether the site needs to be manually re-generated every time a change is made. This website kind of looks like maybe it will be fine? But the truth is that all of this is a bit theoretical for me and I'm not 100% sure if this will work exactly how I hope it will when we put it into practice. The worst case scenario, I think, is that we will put in a lot of work to building this site on Github Pages only to realise that that service doesn't support dynamic CMS, so at that point we will have to decide whether to stick with the 'text editing' and maybe 'regenerating' situation, and getting people to upskill around that, or to decide that the CMS is crucial and we look into the costs of hosting the website somewhere else so the site can be dynamic. Best case scenario is that it works fine on Github Pages and we end up with a completely functional site for freeeee! The other thing that might be a bit ambiguous or confusing here is that while I described earlier how the Static Site Generation of Jekyll works, I don't know ~exactly~ how it works. So I don't know if it's fully static once it's generated or if it can still pull different files together, like the 'blog post' or 'collections' type text files. Because I'm not sure about that, that's why I'm not 100% sure that the CMS we install will work to automatically update the website while it is hosted on Github Pages. but i think it's worth a shot!