Editing the ROOT web site

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:

  1. Get the sources of the ROOT web site and edit them
  2. Generate a local running version of this web site.

Get the ROOT web site sources

You need to follow the following steps:

  1. Make sure have set up git on our system
  2. You should have registered a GitHub account and forked the ROOT web site repository.
  3. 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.

Prerequisites

The prerequisites/requirements are the same presented on the jekyll site.

Install instructions

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:

  1. Install a full Ruby development environment.

  2. Install Jekyll and bundler gems.
    gem install jekyll bundler
    
  3. 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

  4. Change into your new directory.
    cd web
    

    You will notice that the current git branch is main

    % 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 root-project/web/main.

  5. 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 --incremental flag to speed up the rebuild process.

  6. 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.
    
  7. Your server is now running. As shown above, the website can be accessed using a URL similar to https://127.0.0.1:4000/.

  8. 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 similar to:
    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.
    

    once “... done” is displayed you can reload the web site from your browser to see your changes. Remember the --incremental can 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 web/_config.yml

You may notice that the command bundle exec jekyll serve --baseurl="/base" generates a folder _site in the /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.