| title | author | layout |
|---|---|---|
About the HSF newsletter website |
Torre Wenaus |
default |
This site is maintained by the HSF GitHub contributors. If you're interested to become one, contact the [HSF Steering Group]({{ site.baseurl }}/organization/team.html) 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]({{ site.baseurl }}/jekyll-beginners.html) 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]({{ site.baseurl }}/github-beginners.html)!
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]({{ site.baseurl }}/jekyll-beginners.html) 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]({{ site.baseurl }}/organization/team.html)! 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]({{ site.baseurl }}/workinggroups/training.html). To create a new entry you can either:
- Run the interactive script
scripts/add_training_event.py(recommended) - Directly edit the
_data/trainning-schools.ymlfile 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: trueto the YAML file (an example is a school that used a web technology that insists on setting cookies and issues continual redirects without this)
- 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
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]({{ site.baseurl }}/newsletter.html) 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]({{ site.baseurl }}/training/community.html) feature "floating heads" corresponding to profiles of community members. See [howto profile]({{ site.baseurl }}/howto-profile.html) 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:
- default - every page inherits from this
- event - to be used for events
- newsletter - to be used for news items and announcements
- plain - to be used for standard contents
- main - the main page w/ boxes
- minutes - used for meeting minutes (the template adds forward / backward navigation links)
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:
- A meetings block, with links to the minutes of the last three meetings auto-generated
- A news item that holds a small snippet of current important information (currently this is hard-coded, but it would be better if it were more dynamic)
- An activities block, that serves as an entry point to the main sections of the website
They are filled with Liquid snippets.