Humdrum Documentation Website
The development website for Humdrum documentation is: https://www2.humdrum.org
Changes to individual pages can be done within the Github interface: https://github.com/humdrum-tools/newdoc
More efficient editing can be done locally. The following documentation explains how to work locally on the website.
Installation
You need to have git
installed on your computer. For MacOS, install Homebrew, which
will install it automatically.
Downloading
You must first download the website files from Github using the clone
git command:
git clone https://github.com/humdrum-tools/newdoc
This will save the files for the repository in the newdoc
subdirectory in the current
working directory.
Running locally
cd newdoc
./.serve
The first time you download the website repository, you will have to run the command:
bundle install
Then open a web browsers and type in the URL http://127.0.0.1:8000
.
Editing files
You can edit files in the local copy and then refresh the web browser to see the updates. Note that it currently it takes about 4 seconds for updates to be prepared.
In certain cases you will need to restart the local web service by doing
control-C in the windows that is running the .serve
script. And
running ./.serve
again. In rare cases you will need to delete the
compiled website before running .serve
. To do this, type in the
base directory of the repository:
rm -rf _site
This is the directory for the compiled website, so removing it will force a complete regeneration of the files. This sort of case may happen when the configuration file is changed, but usually this situation will not occur.
Putting changes into the cloud
There are a few steps to posting the changes to the website online:
(0) Checking: (1) Adding: Any new files need to be added to the repository (2) Committing: Any changes to repository needs to (3) Pushing: all changes are copied from the local computer to the cloud.
After pushing back to the repository on Github, it will take about
one to ten minutes for the website to update online (Github needs
to recalculate the _site
directory from the source files, and how
fast it does so will depend on the demand of other people's activity
doing the same thing.
Status and adding files to the repository
Type git status
to see a list of the files that have changes in them since the
last commit, as well as a list of files that have changed. You can also
type git diff
or git diff filename.txt
to see changes that have been
made to all files or a specific file since the last commit.
If there are any new files in the repository directories, they need to be added manually. Here is the basic command for that:
git add filename.txt
You can add all new files at once by typing in the root directory of the repository:
git add *
But be careful not to add any junk files in this manner. There is a file called
.gitignore
in the base directory of the repository that lists files/directories that
should be ignored (if you want to keep files in the local directory for the repository
but do not want to add them to the repository, such as the _site
directory).
Committing changes to the repository
You need to save changes to the repository before putting the changes online. This is done with the command:
git commit -am "Reason for the changes"
The -a
option means to commit all changes files (you can also commit files
individually with individual commit messages by removing -a
and giving a list of files to selectively
commit. The -m
option followed by a string will be the commit message. List a short reason why the
changes are being made.
To commit files individually (such as if you want to give a separate commit explanation for each file,
commit each one individually by not using the -a
(meaning all) option:
git commit filename.txt -m "Reason for changing filename.txt"
Pushing changes to the repository
To finally put the changes online, type:
git push
This will copy any new changes to the repository to the cloud. And within a few minutes the updates will be visible on the website. The list of commits on github should now include this one:
https://github.com/humdrum-tools/newdoc/commits/master
Getting changes from the cloud
Before starting to edit files on the local copy of the website, you should run this command from any directory in the repository:
git pull
This will download any new changes to the website since you last downloaded it.
It is important to do this to minimize merges – where your local copy
and the remote copy of a file both have changes. Sometimes these collisions will
need to be resolved manually, but doing git pull
before working on the website
will minimize that problem.
Merging
When you make changes to the website file repository at the same time as someone
else (or technically just after someone else and/or if you forgot to git pull
before starting to edit files), then git will complain:
$ git push
To https://github.com/humdrum-tools/newdoc
! [rejected] master -> master (fetch first)
error: failed to push some refs to 'https://github.com/humdrum-tools/newdoc'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.
If this happens, then type:
git pull
This will cause the new online version of the repository and your local
copy to be merged (locally). Usually this occurs automatically. Sometimes
you will have to fix files if there are changes from two sources that cannot
be resolved automatically. If this happens, git will list the files that
have a problem, and you have to choose which of the two versions of content
should be kept. See this Github page for how to do that. Essentially,
search the files for lines that contain the string =======
and chose the
version above or below that line and delete the unwanted one.
Issues page
To report bugs or tasks for the website, add them to the issues page:
https://github.com/humdrum-tools/newdoc/issues
Original theme
The original jekyll theme for this website is from this repository and the live version which demonstrates various features.
Markdown editing tips
Using code block in embedded HTML
Normally HTML elements that are diplayed with the block
style do not
allow Markdown content inside of them. To use markdown syntax
in these cases, add the attribute markdown="1"
to the elemnt tag.
Example:
<div markdown="1"> This text **is not** processed with `Markdown` </div>
<div markdown="1"> This text **is** processed with `Markdown` </div>