How to Contribute


Welcome

Contributions from the PHENIX community are crucial for this project to succeed. You are most welcome to get involved. Materials that you consider to be relevant to the mission of the site can be sent for consideration to the members of the Data and Analysis Preservation task force.

Direct Contributions

If you are willing to contribute directly by developing the actual content this will be even more valuable and greatly appreciated. For this, you will need to have basic knowledge of the Web platform used on this site. This assumes that you are familiar with the following:

For optimal productivity, you should install the Jekyll web site generator on your laptop or workstation which will allow you to test drive the updated site e.g. after you make a few edits, before commit your changes to the repository. Expert users can leverage the following components of the platform:

Please take a look at the repository to get an idea of the general organization of the data, layouts and supporing logic. The idea is to shape the code and content in a way that is easy to navigate and modify. The following sections explain how this is achieved. Development of this site involves the following aspects:

Site Mechanics
The Navigation Bar and Dropdown Menus

Entries in the navigation bar on top are named in a manner similar to the names of the folders in this project, for example the “Resources” entry in the navigation bar is a dropdown menu with the content defined in a number of files the “_resources” folder etc. These folders are treated as “collections” by the Jekyll framework and they should be declared in the main configuration file _config.yml.

The structure of the navigation bar and the content of the dropdown menus are described in a dedicated YAML file _data/menus.yml. The “name” attribute in each submenu section needs to match the respective attribute in the “Front Matter” of the file with the content of the respective page to be properly linked.

Managing Data

Jekyll is flexible when it comes to storing and manipulating structured data. The data component of the site can reside in the “front matter” section of the Markdown-formatted files or in separate YAML (or JSON, CSV etc) data sources. The front matter approach works well for small sites. For scalability, it is recommended to rely mostly on dedicated data files (i.e. files in the “_data” folder) and keep the content of the front matter sections of individual MD files to a minimum.

The Liquid template language features a variety of filters that can be applied to the data stored in YAML and other data sources as well as in the front matter blocks of pages, and decent (not perfect) support for collections, iterators and flow control constructs.

Information assets on this site (e.g. imaged, PDF files etc) are stored in the aptly named “assets” folder and its subsiduaries. This convention should be kept going forward.

Formatting

We aim to provide a uniform look and feel across the site. To that end, whenever possible the head (title) of each page is formatted by using the standard include layouts/title.md - please look a the code for examples of its use. It’s renders the page title from the front matter sections.

Headers of sections within a page are currently formatted in Markdown as “header level 4” i.e. prepended with four hash characters like in ”#### My section header”. Take a look at the header (Formatting) of this section to get an idea of how it’s rendered.

Development

To productively participate in the development of this site one needs to learn the Jekyll framework and perform its installation on a development machine. This way any modification can be validated immediately since the locally running development server provided by Jekyll will render the site on the local host. Basic knolwede of the Liquid template language and in particular the “filters” that are part of it is extremely helpful.

At the time of writing, this color is used for navigation widgets and icons: #029dcf.