Testing the Website Locally

When making substantial changes to the website, it is quite important to test and verify that your changes to the website behave as expected. The best way to do this is to build the website locally and serve it over local host.

This page describes how to configure your environment for building a jekyll website and serving it locally. It assumes that you already have git configured on your commandline, and that you know the basics of commandline git.

Clone the website

First, you need a local copy of the source. Move to a directory where you would like to keep the repo, and clone it. I, your humble narrator, like having a generic src directory in my home folder.

cd ~/src
git clone https://github.com/ismir/ismir-home.git

You'll then want to move into the docs subdirectory of this repo, where we'll spend the rest of this guide:

cd ismir-home/docs

Installing Ruby

The ISMIR website is written in Jekyll, a Ruby-based framework that allows you to design static websites in Markdown, a lightweight, human-friendly syntax. To build and serve the website locally, you need (at a high level) the following: ruby, bundler, and jekyll.

The safest way to install these is with Jekyll's official instructions.

Install Website Dependencies

The docs directory contains a Gemfile which specifies the ruby dependencies this website needs to be built. We can install them with the following command, issued from the same directory as the Gemfile.

bundle install

Serve the Website

You should now be able to build and serve the website with a single command.

bundle exec jekyll serve

By default, this will make the website appear at: http://localhost:4000

Keep in mind that you can interrupt the website server at anytime with ctrl-C (or equivalent on your machine). It is best to kill and restart the server when you make any changes to the source to make sure that you are getting the latest version of your edits.

Getting more help

When in doubt, refer to Jekyll's documentation for a more thorough explanation of things, or check / create the issues here!