Preliminaries
Installing jekyll
Follow the instructions for installing Jekyll on the website jekyllrb.com/docs/installation and/or https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll
Install git
To check if you have git installed, type on the command-line (terminal):
which git
which should reply with something like:
/usr/local/bin/git
If you are using an MacOS computer and you do not have git, then install Homebrew. If you have windows, the good luck—although Windows 10 now comes with a https://msdn.microsoft.com/en-us/commandline/wsl/install_guide that you could try. If you do not have git on a linux/unix operating system, then try typing one of these:
apt-get install git-all
yum install git
dnf install git-all
See https://git-scm.com/book/en/v2/Getting-Started-Installing-Git for more information.
Also, if you like GUIs, then read this link about https://git-scm.com/downloads/guis.
Download the website
After git is installed, you can download the VHV documentation website with the command:
git clone https://github.com/humdrum-tools/vhv-documentation
This will download the website to the directory ./vhv-documentation.
Running the website
Go into the vhv-documentation directory (wherever you have stored it). Then type:
./.serve
This will compile the website and allow your web browser to access the website from the address
http://127.0.0.1:2000.
Running the website offline
If you are not going to have access to the internet when accessing the website, then you can run the website in local-only mode by typing:
./.serve-local
In order to use this script, you will first have to download the verovio-script.js file
by going into the js/local directory and typing make in the terminal. This only has to
be done once, but you can repeat the download to ensure that you have the most recent
version of the verovio-toolkit.js file.
Editing pages locally
The easiest way to add or edit pages on the website is to install the website locally. After you make changes, do these steps to update the online website hosted at Github pages:
#1 First type git status to see what files have been changed, and what new files
need to be added to the repository.
#2 Check the files which are new, and then type
git add myfile.txt
to add the new file myfile.txt to the repository.
#3 After all new files have been added,
type git commit -a to add the changes to the local repository. This command will
typically open the vim editor and you will type a brief description of the changes
made to the documentation.
#4 Finally type git push to copy the changes from the local
computer onto the Github servers.
If you do not have access to write to the documentation repository, you should instead submit a pull request (more on how to do that later).