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.
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.
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.
If you are not familiar with GitHub and Git, you can read our survival kit!
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.
The recommended way to host a collaborative note book, e.g. for taking meeting minutes (live notes), is to use a collaborative editing tool utilising Markdown directly. This makes it trivial to move the content into the HSF website for archiving.
CodiMD is the suggested choice as it has been designed for collaboraitve editing of Markdown files. Unfortunately, the Hackmd free service is now restricted to 4 editors. Another possibility, if you have a CERN account, is to use CERNBox which makes CodiMD available to edit Markdown files: you 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.
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.
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.
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. The minutes file must be placed into Jekyll organization/_posts directory.
The only edit required is the replacement of the front-matter section by the one present in the previous meeting minutes in Jekyll, updating the title (meeting number and date).
Before adding any new activity or proposing a new working group please discuss with the HSF Coordination Team! We will make sure it gets proposed in an HSF meeting for approval.
Then, for the technical creation, add a new file in the _workinggroups or _activities directory. Follow the front-matter of the
other files in there. The Working Groups / Activities menu in the navigation bar will
be updated automatically: the menu entry text is the title attribute in the front-matter section.
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.
For training events we have a special handling that lists all of these together on the Training Working Group page. To create a new entry you can either:
scripts/add_training_event.py (recommended)_data/trainning-schools.yml file and add another entry following the structure of the existing entries (note that events are sorted chronologically by starting date)
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)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.
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).
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.
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 working groups and activities are generated
automatically.
The main page contains three blocks, mostly hard-coded:
They are filled with Liquid snippets.