How to Contribute to The Web Site
Table of Contents:
- How to add and edit information
- 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
masterbranch 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
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
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.mdfor an example.
- In the front-matter section of this file, add the attribute
menuwhose 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