The ROOT team has adopted Jekyll for generating the ROOT website. The ROOT website uses a forked copy of the “Minimal-Mistakes” theme. Many scripts and functionalities have been added compared to this original theme.
This page provides instructions to generate a local running version of this website. The informations presented here are largely inspired from the quick start page of the Jekyll website.
Generate a local running version of the ROOT website
The prerequisites/requirements are the same presented on the jekyll site.
The install instructions differ a bit from the ones you can find on the Jekyll website as you do not need to create a new website but instead get it from GitHub. So the steps are:
Install a full Ruby development environment. There might be compatibility issues with Ruby 3. If that is the version that comes with your system package manager, you can install Ruby 2.7 next to it using tools like
- Install Jekyll and bundler
gem install jekyll bundler
- Get the ROOT website source from GitHub.
git clone https://github.com/root-project/web.git
You can also use your own fork, of course, but see Get modifications upstream below.
- Change into your new directory.
You will notice that the current git branch is
% git checkout Your branch is up to date with 'origin/main'.
This branch is the one from which the official website is built. You can create a new branch with your work, which you can use to create a pull request to update
- Some missing gems might need to be installed. The following command, run
webdirectory, does it:
If you’d rather install the packages in a local directory, configure
bundleto do so before running
bundle install. This can be done with:
bundle config set --local path 'vendor/bundle'
Note: to update all the gem dependencies to their latest versions you can run
- Build the site and make it available on a local server.
bundle exec jekyll serve --baseurl="/base"
If you only plan to make minor modifications, you can append the
--incrementalflag to speed up the rebuild process.
- After about 30 seconds you should get an output similar to
Configuration file: /path/to/the/directory/_config.yml Source: /path/to/the/directory Destination: /path/to/the/directory/_site Incremental build: disabled. Enable with --incremental Generating... Jekyll Feed: Generating feed for posts done in 21.638 seconds. Auto-regeneration: enabled for /path/to/the/directory Server address: https://127.0.0.1:4000/ Server running... press ctrl-c to stop.
Your server is now running. As shown above, the website can be accessed using a URL similar to
- Work on the website.
Each time you create a new file or save a modified version of a file
the server will notice it and will regenerate the website. You will get an output
Regenerating: 1 file(s) changed at 2020-02-19 10:40:02 for_developers/index.md Jekyll Feed: Generating feed for posts ...done in 9.877795 seconds.
... done” is displayed you can reload the website from your browser to see your changes. Remember the
--incrementalcan speed up serving times considerably.
It is not necessary to restart the server each time you do a modification except if you
modify the file
You may notice that the command
bundle exec jekyll serve --baseurl="/base" generates a folder
/path/to/the/directory/web/ folder. This is the html version of the website. Do not
modify or create files in that folder. This folder is ignored by git.
Get modifications upstream
Once you are happy with your modifications, you can publish them via a
“Pull Request”. You
can either push a branch to your fork of the website repository, and create the pull
request from your fork to https://github.com/root-project/web, or
if you have write access to the
root-project/web repository, you can directly push a new branch upstream.
Note that only pull requests that originate from branches that belong to the upstream repo (not forks) benefit from the
test deployment of pull requests: a preview
website with the changes contained in the PR is served from
https://root.cern/<PRNumber> after the CI job for the PR
When a pull request is merged,
https://root.cern will be updated automatically
after a short while.