CorrelAid NL Website

This is the repository associated with (the revamp of) our website. It is built using Jekyll and based on the Vonge Template theme.

Approach

Our original website was made by forking the main CorrelAid website made using Hugo. This was a quick way to get a website up and running with a familiar look and feel. In 2022, we decided to reboot the website. With the existing codebase being somewhat messy, we decided to start again from scratch. The choice to use Jekyll, rather than Hugo, was motivated by its built-in support for website hosting via GitHub. Unfortunately it turns out that our choice of template includes some packages that GitHub Pages does not support. The list of packages can be found here. The naming of this page is unhelpful, but for things to work automatically, don't use something not on this list. At the time of writing, they also do not have a meaningful build error message when using an unsupported package. Fortunately there is a way around this which will be explained below. The sharper reader may now realise that the original rationale for using Jekyll is somewhat undermined by this issue.

How It Works

Our website is hosted with GitHub Pages. It allows us to host a website for free for our GitHub organisation. A special .io repo is made. This creates our github.io website. As owners of the CorrelAid.nl domain, we can make this appear at our preferred URL.

This repo holds the code base for generating the website and is where we make changes to it. It follows a familiar CI/CD framework. The idea that any commits to the master branch will trigger a redeployment of the website. I deliberately say redeployment here rather than rebuild because we need to build the website locally ourselves.

As mentioned in the intro, the website is made using Jekyll. This is a static website generator. Rather than having to code HTML explicitly or have them generated by the server on the fly, this approach allows us to work with templates, but all pages are generated upfront when building and deploying. We are using a free Jekyll template made by Cloud Cannon. However, we are not using their interface or services to maintain the website.

General Logic

Currently, the content of our website falls into three main categories.

• Pages. Here we define custom pages specifically, e.g. the about page. When adding a new page, its inclusion in the overall website navigation (to make it findable) needs to be implemented. For this reason, adding a page is somewhat more involved than adding other type of content. NB: many pages are created automatically on-the-fly when adding other types of content.
• Projects. Project posts are meant to be short standardised descriptions of our projects. Adding a project will include it in our Project page (and also initially on our homepage) and create a new page for the project. Note that longer in-depth posts about projects should be done as a Post in addition to a shorter Project (post). The idea of this content section is to have a short description of every project.
• Posts. Posts are rather free-form and can be on any topic. A typical blog post could be a deep dive into a project or a personal CorrelAid NL journey of a volunteer. Adding a (blog) post will include it on our Blog page (and also initially on our homepage) and create a new page for the post.

Technical Instructions

Updating the Website

If it is your first time updating the website, please first check the section Getting Started below. The basic recipe for making a change is as follows.

1. Create a new branch on this repo and checkout this new branch locally.
2. Make the desired changes and test locally, i.e. build and deploy on localhost. The cmd line command for this is "bundle exec jekyll serve". You need to execute this from the 'site' sub-folder rather than the root directory. This command builds the website in the _site subfolder with your localhost of the root URL. The command prompt should give you a link with the server address so that you can check the website in the browser.
3. If you are happy with the result locally, then you need to locally prepare for deployment on the server. On the server, the \docs folder will effectively be copy/pasted for deployment. To make a deployment ready version of the website, rebuild the website with the command "bundle exec jekyll build -d ../docs". This command (with build NOT serve) takes the actual URL of our website (correlaid.nl) as the root URL. If we didn't do this, and just used 'serve', we end up with references to localhost appearing on the website and some broken links. The '-d ../docs' part of the command sets the build destination to the docs folder. GitHub pages only supports deployment from either the root or docs folder for some reason.
4. Manually correct the pagination links for the blog posts (see General Tips for details) and possibly also project posts in the future.
5. Push the changes to origin and merge to master branch.
6. Check that your changes are visible in the live website.

To add new contact to the website, you follow the following recipe.

1. In the site folder (note the lack of _), go to the collections folder. This folder stores the individual pieces of content divided by category. Currently, we are actively using the _posts section for blog posts and the _projects section for project descriptions.
2. Go to the relevant subfolder for the type of content you wish to add. Copy the _template file and rename in logical way. Take care that the new name does not start with an underscore otherwise it is excluded from the website build.
3. Change the values in the file header ('front matter' in Jekyll lingo) to fit your post and add your post content. Make sure you remove the square brackets used in the template to demark where content is needed. In case of doubt, you can always check the files for existing posts as reference.
4. Add any image files you are using to the images folder.

Further details about how to add certain standard content should be added here, for example, regarding the preferred sizing of images.

General Tips

Sometimes websites don't work as you expect, welcome to the world of front end development! Here are some tips.

• Cache. To avoid continuously downloading the same files, browsers make extensive use of caching. This means that a change to an existing file will not be immediately visible, since the browser will simply serve the old version of that file from the cache rather than downloading the new one. To see you changes when this happens, do a hard refresh of the page (e.g. ctrl-shirt-r for Firefox on Windows.)
• Tags. The website allows you to assign tags to posts which are then displayed with the post as a link. This allows users to easily navigate to other posts on the same topic. However, the system automatically capitalises the first letter and doesn't support spaces. Please only use single word tags to avoid broken links or strange formatting.
• Pagination. When there are many items, Jekyll can split them across multiple pages (known as pagination). Sadly the Vonge template has implemented this in a way that only works properly when deploying via CloudCannon. On their website, this issue has been acknowledged. As we are deploying via GitHub, this is a problem for us. Some of the links created for the pagination (to move between the various split pages) will be broken. This seems to happen when the pagination extends beyond two pages, which is why we didn't notice it at first. We haven't found a simple and proper solution to this, possibly the codebase of the template needs some non-trivial changes. A manual fix is to overwrite those links after making the build. For example, going to the docs/blog/page/2/index.html file and changing the href for pagination__next from "../../." to "../../page/3/". This needs to be done for all links between pages 2 and greater, sadly.
• Build Locally. Since we are using packages not supported by GitHub Pages, we cannot build on the server. Please check that the instructions in the section Updating the Website have been fully followed. If you haven't copied the newly made website files to the docs folder, then it will redeploy the old version. If you haven't added the empty .nojekyll file to the root of the docs folder it will fail to build on the server. If you haven't built the website using the build command (i.e. using serve instead), then we will get references to localhost and broken links.
• Case Sensitivity. Behaviour can be inconsistent with regards to the cases of filenames and their extensions. To avoid a gotcha with filenames, make sure the extensions are in lower case.

Getting Started

Certain standard items from the data science toolkit are assumed here.

• GitHub account with relevant access rights.
• Basic familiarity with git.
• Basic familiarity with markdown.

In addition, experience with html and css is helpful, but not a must. The main specific thing to do is to get set-up and familiar with Jekyll. If you want to have some hands-on practice with Jekyll, I suggest making your own personal GitHub pages website, which uses an identical approach.

Beyond installing Jekyll, there are two other dependencies for the specific template we are using. This template uses Node.js which you can download and install from here. You may also need to set up Jekyll Watch, but whether this is truly necessary is still to be verified by a new user. You of course need to clone this repo, and then make sure you can build and run the website locally.

If you want to be able to make more significant changes, it might also be good to check out the codebase for the theme we are using.

A previous developer of the website followed a different approach to installation. It is included below in case it is useful to some new users, but has not been road-tested. Accordingly, it is recommended to follow the instructions above, with those below provided for completeness in case of use to some users.

$ npm install

Install the Jekyll dependencies with Bundler:

$ cd site
$ npm run install-jekyll

Run the website:

$ npm start