How to Contribute to The Web Site

Table of Contents:

• How to add and edit information
  • General structure of website content files
  • Adding a working group
• Useful references

This website is implemented using GitHub Pages service which makes it easy to create a website associated with a GitHub account or project. GitHub Pages uses Jekyll, a tool to automatically build a website from source files (which are kept in GitHub). The site content is written using the easy Markdown syntax (which is used by GitHub itself).

A beginner’s guide provides some useful hints to make using Jekyll in the HEPiX context easier. It is recommended to read it if you are not familiar with Jekyll.

How to add and edit information

For adding information to this site or modifying it, we follow the pull request workflow in GitHub.

You must start by forking our website repository and then, clone your fork (not the website repository) with your preferred Git client. Once you have done it, for every contribution you’d like to make, the workflow is:

• Get the last updates from the web site repository with:

    git fetch --all
  

• Create a development branch from the web site repository (do not use the master branch for your contributions, avoid reusing an existing branch if you are not familiar with Git) with:

    git checkout -b dev_branch upstream/master`
  

• Edit the files you want to add or modify

• Push them to your fork with:

    git push --set-upstream origin HEAD
  

• Open a pull request with the GitHub web interface (GitHub should propose to it when you open either the web repository or your fork)

If you wish (and it is recommended), you can easily set up a local instance of this web site in order to preview your submissions. See the documentation on installing and running Jekyll. The website uses the master branch of the hepix-forum.github.io repository.

If you are not familiar with GitHub and Git, read our survival kit!

General structure of website content files

All Markdown files of this site start with a section surrounded by ---. This so-called front-matter section contains metadata about the content. Such metadata are e.g. the author of the document or the title of the document.

In the front-matter (but not in the text itself), you need to replace any & characters (which has a special meaning in HTML) by &. This is particularly important for the title attribute.

Adding a working group

To add a working group in the main menu and to allow to add pages attached to this working group, it is necessary to:

• Create a file at the top level, whose name represents the working group name, e.g. mywg, and with the extension .md. Look at benchmarking.md for an example.
• In the front-matter section of this file, add the attribute menu whose value will be the menu name in the page main menu.
• Create a directory _mywg (if the group name is mywg) to contain additional pages for the working group

Useful references

• Jekyll to build websites from plain text
• The Liquid template engine used by Jekyll
• Markdown syntax