The ROOT team has adopted Jekyll for generating the ROOT web site. The ROOT web site uses a forked copy of the “Minimal-Mistakes” theme. Many scripts and functionalities have been added compare to this original theme.
This page gives you the instructions to:
- Get the sources of the ROOT web site and edit them
- Generate a local running version of this web site.
Get the ROOT web site sources
You need to follow the following steps:
- Make sure have set up git on our system
- You should have registered a GitHub account and forked the ROOT web site repository.
- Clone your forked ROOT web repository locally on your machine using:
git clone https://github.com/<your GitHub username>/web
You now have a copy of the ROOT web site sources from github. You can work on them, play with a locally served website (next section), and finally create “Pull Requests” to get changes upstream.
Generate a local running version of the ROOT web site
This section gives you the instructions to generate a local running version of the ROOT web site. The informations presented here are largely inspired from the quick start page of the Jekyll web site.
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 web site as you do not need to create a new web site but instead get it from github. So the steps are:
Install a full Ruby development environment.
- Install Jekyll and bundler
gems. This command
might need to be run in
gem install jekyll bundler
- Get the ROOT web site source from github.
git clone https://github.com/root-project/web.git web
You can also clone a forked copy from you own github as explained in the section on getting the sources
- 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 web site 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, ran
webdirectory, does it:
- 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 web site. 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 web site 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 web site. 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.
If you create a pull request “inside”
root-project/web, github can create a preview website, which
will be served at
https://root.cern/<PRNumber> (after the build step completes).
When a pull request is merged,
https://root.cern/ will be updated automatically
after a short while.