Getting the source
The website 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.
Visit this page for information about installing Ruby if your current version is too old; the instructions there form the basis for what you see here, and come in variants for all major operating systems. You should have Ruby 2.4+ for Jekyll. Since versions of macOS before Catalina with 2.3 (and Apple is dropping scripting language from macOS in the future), you may 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.7.1
to get a current version of ruby. Then, inside the main iris-hep website directory, run:
rbenv local 2.7.1
This will run the Ruby you just built whenever you enter this directory. You’ll want to install bundler too:
gem install bundle
(You may want to add
--user-install here if you are not using rbenv. And if
you don’t have permission to install, and you are using rbenv, this means you
forgot to set it up with
The site is built with Jekyll, and is easy to run locally if you have Ruby.
To set up a “bundle” (local virtual environment in Python terms):
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 execbothers 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
.git/safe/../../bin. This will give you a per-folder controllable way to dd
./binto your path. Now, you can just use
rakeand 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
clobber targets are available (the later removes the Inspire-HEP cache as well). You can also run
bundle exec jekyll ... directly.
/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
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.
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.
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.
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_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.