Getting the source

The webite source is available at https://github.com/iris-hep/iris-hep.github.io-source.

You can always click the edit button to make small edits to the website source, but if you want to test locally or make larger edits, you’ll want to clone the source for the website and build it with Ruby.

Installing Ruby

You should have Ruby 2.4+ for Jekyll. Since the latest macOS comes with 2.3 (and Apple is dropping scripting language from macOS in the future), you’ll want a newer version even on a mac. You can use rbenv to manage multiple ruby versions. On macOS with homebrew, you’ll want:

brew install rbenv

You’ll need to run rbenv init and follow the instructions for your current shell. After you’ve installed rbenv on your system, use:

rbenv install 2.6.3

to get a current version of ruby. Then, inside the main iris-hep website directory, run:

rbenv local 2.6.3

This will run the Ruby you just built whenever you enter this directory. You’ll want to install bundler too:

gem bundle

Running locally

The site is built with Jekyll, and is easy to run locally if you have Ruby. Visit this page for information about installing Ruby if your current version is too old.

To set up a “bundle” (local virtual environment in Python terms):

bundle install

Now, you can use bundle exec to run a command in the new environment you just created, such as:

bundle exec rake serve

Note: If prefixing everything with bundle exec bothers you, you can run bundle --install binstubs, then use bin/* to run commands. See this page for more info. You can then add a folder mkdir -p .git/safe, and add the following to your PATH: .git/safe/../../bin. This will give you a per-folder controllable way to dd ./bin to your path. Now, you can just use rake and other commands directly.

This will incrementally rebuild if anything changes in your directory. Exit with Control-C. If you want to build the site including all basic link checks (this should pass on master):

bundle exec rake check

If you want to also perform the full link checking without exclusions, you can run:

bundle exec rake checkall

If you are not familiar with it, rake is short for “Ruby make”. The clean and clobber targets are available (the later removes the Inspire-HEP cache as well). You can also run bundle exec jekyll ... directly.

Updating javascript files

If you add or change a javascript file, you need to edit the page /includes/head.html and add the new hash in the identity part of the script include. You can generate the hash for a file, like assets/js/myfile.js, using:

cat assets/js/myfile.js | openssl dgst -sha384 -binary | openssl base64 -A

Run the site locally and verify no warnings appear in your terminal. Also turn on your browser’s debugger and make sure no warnings are emitted.

Styles

Most style changes should be set in assets/css/style.scss. Some basic changes, like color variables, are set in the _sass directory. Please remember to consider multiple screen widths, printing (for relevant pages), and dark mode when changing or adding styles. You can see the defined colors here.

Caching

The website has two forms of caching. It will save InspireHEP access data in _cache, and it optionally can download the Indico accesses to _data/indico. If you use

bundle exec rake clobber

You will remove the cache (clean will only remove the web files, not the cache). If you want to generate the optional part of the cache, you can run

bundle exec rake cache

The InspireHEP access caching is automatic and is part of the normal Jekyll build.

Accessing Indico

The Indico access needs a key to authenticate to get protected meeting listings. This is normally done by Travis, but you can do it yourself by setting the INDICO_API_KEY and INDICO_SECRET_KEY environment variables (see this page for information on how to generate these keys). The keys use timestamped requests, so your system clock needs to be roughly correct.