About the HSF website

This site is maintained by the HSF GitHub contributors. If you’re interested to become one, contact the HSF Steering Group or any team member. It was set up by Torre Wenaus and Benedikt Hegner.

Implementation

This website is implemented using GitHub’s Pages service, which makes it easy to create a website associated with a GitHub account or project. Pages uses Jekyll, a tool to automatically build a website from source files (which are kept in GitHub). It supports structured sites like blogs in a simple but powerful way. The site content is written using the easy Markdown syntax (which is used by GitHub itself).

A HSF documentation provides some useful hints to make using Jekyll in the HSF context easier.

How to add and edit information

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

Just fork our HSF website repository, edit the files you want to edit, push them to your fork, and open a pull request.

If you wish (and it is recommended) you can easily set up a local instance of the newsletter site in order to preview your submissions. See the documentation on installing and running Jekyll. The website uses the main branch of the hsf.github.io repository.

When you make a pull request to the website repository, Netlify will build a preview version of the website with your PR. This will allow you to double check the update looks the way that you intended (check for the Deploy Preview URL in the PR; it will be something like https://deploy-preview-1644--earnest-hotteok-b1e1bf.netlify.app/).

If you are not familiar with GitHub and Git, you can 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 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 content from collaborative tools (live notes)

Markdown file

The recommended way to host a collaborative notebook, e.g., for taking meeting minutes (live notes), is to use a collaborative Markdown editor directly. This makes it trivial to move the content into the HSF website repository for archiving.

If you have a CERN account, one can create a Markdown file in CERNBox, using CodiMD to edit this in a browser. One can then define a public link to the document (similar to Google Docs public links) to allow those without a CERN account to edit the file. Similarly, the Helmholtz Association has a web based Markdown instance that can be used at https://notes.desy.de, which should be available to most people with an EduRoam login.

We find that recycling the same document for a series of meetings is extremely useful as the live notes link can be copied and cloned from one meeting to the next.

GoogleDocs

Google Docs can also be used for shared notebooks, but in this case there is a need to convert the document to Markdown before it can be added to the website. This is less convenient, but we have documentation on how to do it.

Adding coordination meeting minutes

HSF Coordination minutes are produced using the live notes approach described above. The content of the live notes are preformatted to be suitable for direct injection into Jekyll, after minimal edits described in the running-meetings page. The minutes file must be placed into Jekyll organization/_posts directory.

Adding an Activity Area

Before adding any new activity or proposing a new Activity Area please discuss with the HSF Steering Group! We will make sure it gets proposed in an HSF meeting for approval.

Then, for the technical creation, add a new file in the _activities directory. Follow the front-matter of the other files in there. The Activities menu in the navigation bar will be updated automatically: the menu entry text is the title attribute in the front-matter section.

Adding an event

Add a new file in events/_posts and follow the front-matter (see above) of the other files in there. The Events page and the Upcoming Events sidebar will be updated automatically.

Adding a training event

For training events we have a special handling that lists all of these together on the Training Activity Area page. To create a new entry you can either:

  1. Run the interactive script scripts/add_training_event.py (recommended)
  2. Directly edit the _data/training-schools.yml file and add another entry following the structure of the existing entries (note that events are sorted chronologically by starting date)
    • There is one very rare thing you may need to do if the URL for the training event will not validate in the link checker, which is to add the tag url_proof_ignore: true to the YAML file (an example is a school that used a web technology that insists on setting cookies and issues continual redirects without this)

Adding news or announcements

Add a new file in announcements/_posts and follow the front matter of the other files in there. The front page will get a new box with all information.

Please don’t forget adding an event until in the front-matter: this is used for ordering events and as the end date for adding the event in the Upcoming Events sidebar.

Adding a newsletter

Newsletters are occasional longer articles we publish. Each of these lives in newsletter/_posts. The format is very similar to the other content on the website, follow the front matter of the other files in there.

You can highlight a newsletter by updating the centre column of the frontpage of the website (see below).

Adding your profile

Some pages, like the training community page feature “floating heads” corresponding to profiles of community members. See howto profile for how to create your profile and how to include selected profiles into a page.

Technical details

Page templates

As of writing, this website contains the following page templates for wider usage:

The menu bar is defined in _includes/navbar.ext, from which all page layouts inherit. The layout is somewhat hard-coded, but activities are generated automatically.

Main page

The main page contains three blocks, mostly hard-coded:

They are filled with Liquid snippets.

Useful references



Improve this page. Thanks to GitHub Pages, Jekyll and Bootstrap.