Mon 3 Jul 2017 1:47PM

Use a static site generator for the CoTech website and host on GitHub Pages

CLF Chris Lowis (Go Free Range) Public Seen by 69

Howdi folks,

We (Chris, Chris and James at Go Free Range) would like to propose that we move our CoTech website to Jekyll and host it on GitHub Pages. Jekyll is a static site generator and GitHub Pages is a free host for static content.

While we appreciate all the effort that's gone into our current WordPress setup we’re concerned that the complexity makes it harder to make changes (to the site as well as the content) than it needs to be.

To help those unfamiliar with Jekyll to understand this proposal we’ve ported the look-and-feel of the existing CoTech website and some of the content. You can see the generated site at https://cotech.github.io/statically-generated-website/ and the code at https://github.com/cotech/statically-generated-website.

This prototype gives us confidence that changing to a static site generator is technically possible and that the result will be simpler than our current setup.

Advantages of switching

  • All our site content (text, data and media) will be under version control
  • Changes can be made using the GitHub user interface
  • Changes can be discussed using Pull Requests (avoiding the current wiki/Loomio process)
  • Deploying becomes as simple as pushing commits to GitHub
  • The site hosting is free
  • Local development only requires Ruby
  • No servers to manage, security updates to apply, or databases to backup
  • Switching to an alternative static site generator is relatively easy
  • Switching to an alternative host is relatively easy
  • Less moving parts mean that it's simpler overall


  • We lose the existing Wordpress admin interface for editing data
  • Users will need (free) GitHub accounts to make changes
  • Knowledge of Liquid required to make logic changes

Next steps

If we turn this into a proposal and it is accepted we’ll commit to porting the existing content over to this system so that the transition is as painless as possible. We’ll also be happy to help anyone in the network learn how to contribute using git and GitHub. If you’re interested in the kind of things that need doing next we’ve added some information to the README.

We'd love to answer any comments or questions before we make this into a proposal.


olizilla Mon 3 Jul 2017 1:59PM

I love the cotech site but I'd be more eager to contribute to it if it was as a generated static site of any flavour, and we run a bunch of things of gh-pages so we have some jekyll experience, so I'm all +1


James Mead (Go Free Range) Mon 3 Jul 2017 2:27PM

To give you more of a flavour for how this works, I've opened a pull request to add the Altgen coop and some of clients, services & technologies. The new files are shown here. The nice thing is that it's very easy to collaborate on the changes via the GitHub PR interface - in particular you can add comments against a particular line of code. And the changes can be deployed simply by merging the PR with the big green button!


Harry "Outlandish" Robbins Mon 3 Jul 2017 2:30PM

I agree that it would be good for it to be easier to update, and I've been pretty frustrated about not being able to deploy changes.

That said, having it moved to a new system that I don't understand would be more annoying for me and would prevent me making future changes. As a non-developer I find all the pull requests + tooling stuff really confusing. I'd be concerned that losing the CMS would make it less easy for non-technical people to update.

We've also just commissioned some work to add individuals and 'jobs/skills/availability board' to the site, which would require dynamic database stuff (and a CMS).

Might another option be for people to contribute different elements to the site? e.g. some design co-ops could do some design work, some hosting co-ops could host it, etc?

Another option would be to move it to being a 'headless' WordPress site, where all the data is stored in WordPress but the business logic, etc. is done with React or similar. That has its own challenges though.

All that said though, things are clearly not working at the moment so something has to give.


Simon Grant Mon 3 Jul 2017 2:38PM

In principle I'm in favour of moving to Jekyll, even though I am not a developer. Why? Because I know I am highly unlikely ever to (want to) get sufficiently far into Wordpress that I could actually make any reliable changes to any theme, whereas with Jekyll it looks (again in principle) much more accessible.

GitHub (or at least Git) seems fast to be becoming an essential collaborative skill, and like @harryrobbins I'm still far from fluent in it. But I would very much like to be. My guess is that fluency in GitHub and Jekyll would take an order of magnitude less time than fluency in WordPress theme work, and so I am completely up for a learning group on this.


Alex WA Mon 3 Jul 2017 2:44PM

Static site generators are a great technology and confer many advantages as you describe (another is scaleability and disaster recovery).

However they also have a number of disadvantages which include:
- They require a knowledge of, at minimum, Git, Markdown and the framework in question (here Jekyll but could be Hugo or anything else), the idea of PRs etc. A blog is a more familiar technology and more accessible - we aren't all developers. I've tried to introduce flat file management to non-developers and it is surprising how it all seems "simple" to us but is anything but.
- As soon as you get into the world of adding a large amount of structured data to the mix (skills, interlinks, API like functionality, clients, collaborations etc) you begin to question wether having no database is such a clear advantage overall. You begin writing things that get out and query the structured data on the Markdown files to produce a JSON blob - independently re-creating a CMS.

There are editors which sit over the top of Git and Markdown as a simple piece of wrapping to the complexity...but introducing these seems to be re-inventing what you originally attempted to move away from...


Simon Grant Mon 3 Jul 2017 2:48PM

@alexwa I'd be interested in your or anyone's experiences of non-developers learning basic GitHub skills. Personally I can't see Markdown as a barrier, as most of us non-developer types are reasonably familiar with the different-but-similar-in-principle Wikitext


James Mead (Go Free Range) Mon 3 Jul 2017 2:46PM

For those not familiar with GitHub, I should point out that it's perfectly possible to make changes through the GitHub user interface, i.e. you don't have to use the git command line.

I'll see whether I can open up the permissions on the prototype repo so people can have a play.


James Mead (Go Free Range) Mon 3 Jul 2017 3:10PM

I've now moved the repo to the cotech GitHub organisation so anyone who already belongs to that should be able to make changes. The new repo is here and the deployed version is here. I'll update the links in the thread context now.


Simon Grant Mon 3 Jul 2017 2:54PM

Oh, and I'd also like to appeal to ICA Principle 5 and Principle 6. Seems to me that a co-operative learning exercise in useful skills would be a great example of doing some of both principles together -- even were we to decide not to go that way.


James Mead (Go Free Range) Mon 3 Jul 2017 2:55PM


There are editors which sit over the top of Git and Markdown

The GitHub web interface means you can edit stuff without needing much of an understanding of git. Have you ever edited a file directly on GitHub?

Also the GitHub web interface editor provides a rendered preview of Markdown documents.

Load More