How to edit the MRSHub website (MRSHub.org)

The MRSHub website is generated from simple text files, using the popular static site generator website Jekyll. It is built and served through the free service Netlify.

The text files that the site is built from live in the 'master' branch of a GitHub repository of the MRSHub account. Whenever the files in this repository are changed, Netlify compiles the Jekyll files and rebuilds the website automatically.

To maintain and update the MRSHub website, you will need to set up two software packages on your computer:

• Jekyll to test changes locally before committing them to the GitHub repository where the website text files live. Follow the Jekyll installation guide to set up Jekyll.
• Git (and optionally the GitHub Desktop software) to track and commit changes you make in your local copy to the website repository.

MRSHub website maintenance workflow

1. Clone the 'develop' branch of the website GitHub repository into a folder of your choice on your computer.

2. Make changes to files as you see fit. The MRSHub website is built around the widely used and well-supported Minimal Mistakes theme.

3. To test the changes you made locally, open a terminal or prompt, navigate to the folder you just created (so you can see the file _config.yml).

4. Type the command jekyll serve and hit Enter. If you see jekyll producing errors at this stage, try using the command bundle exec jekyll serve instead. If that does not resolve the problem, re-installe and upgrade Jekyll (follow the Jekyll installation guide again). After upgrading to Jekyll 4.2, I previously had to add a deprecated dependency with the command bundle add webrick (instructions here).

5. After a while, you should see a line Server address: http://127.0.0.1:4000/. You can copy the address into your web browser and test the functionality of the local copy of the site. Make sure that all the changes you made appear. Back in the terminal window, hitting Ctrl-C will stop the local Jekyll server.

6. If you're happy with the local rendering of the site, commit the changes back to the 'develop' branch of the repository.

7. Submit a pull request from the 'develop' branch to the 'master' branch of the repository. The site will then automatically be rebuilt by the Netlify host service. You can check the status of the rebuild by logging into Netlify with the MRSHub GitHub account credentials. Once the build is successful, the MRSHub website is live without further ado.

Common error messages

The bundle exec jekyll serve command in step (4) above may fail if Markdown files for adding new entries to the data or software collections are formatted incorrectly. This is not always obvious, but almost always means that you are using a special character in a text field that you are not allowed to use. Pay particular attention to "" inside other "", backslashes / and colons : - when in doubt, remove them and see whether the error persists.