How to contribute

We decided to keep some control over what’s published by merging Pull Requests. So please fork, modify, PR and then we’ll merge your changes. Please see this guide to create a Pull Request.

How many languages are used when editing a Jekyll webpage?

About four. But often you only need to use one. The four languages you have to know a bit about in order to use Jekyll are:

1. Markdown, Github flavour
   • Lightweight markup language
2. HTML
   • Markup language
3. Yaml
   • "YAML Ain't Markup Language"
   • Used for configuration files
4. Liquid
   • Template engine/language
   • More documentation

If you are aesthetically ambitious, you will also dig into CSS. And, of course, further below the hood, there is Ruby, Gherkin, shell-scripting, etc

Local development environment

If you would prefer to generate a dummy website to make sure it looks exactly as you want before pushing it, you can create your locally served website. To do so, follow the instructions provided for the imagej.github.io pages about Jekyll and Git.

Uploading your changes

Small edits can be done directly in your browser in GitHub.
Larger changes to the structure must be done locally, then pushed to GitHub.

If you are an editor of the repository you can do edits of this repository directly with your method of choice.

Most members are not editors, but read-only rights still allow to make make a so-called pull request: Clone this repository, edit it, commit your changes to the relevant branch and create a pull request. Then one of the editors have to accept (merge) your contribution before it will appear in the published webpage.

Adding pages

To add a webpage, create it as markdown or html and place it in _pages (become and editor or create a pull request for this). You can link to it from another page or add it to the navigation menu (be conservative -- navigation bars quickly become crowded).

Adding a member page

Each member have their own markdown file, stored in the /_members directory. It consists of a YAML frontmatter (between the triple-dashed lines) and document body written in Github flavored markdown. Bellow is an example, from the file simon.noerrelykke.md:

---
first_name: Simon F.
last_name: Noerrelykke
short_name: simon
city: Zurich
affiliation: ETH Zurich
position: Image Analyst
tags: [matlab, fiji]
---

Simon works at ETH Zurich.\\
He heads [IDA](http://let-your-data-speak.com/) - the Image and Data Analysis group inside of ScopeM.

To create a new member file, copy an existing file, rename as [firstName].[lastName].md, change all text that needs changing, and save it in /_members (commit it and create a pull request if necessary).

Front Matter conventions:

• The city attribute should only be used for Swiss cities and left empty otherwise. To add a new city not yet present on the map, you also need to observe this section
• The affiliation attribute can hold only one institution/company. Use its main name and put the detailed description in the document body.

That is it! The new member will automatically be added to the list of all members and have their own page with the text they provided, e.g. https://www.swissbias.ch/members/simon.noerrelykke.

Note: Check the web inspectors console of the member page, to see if there are problems with the member locations and the rendering of the map.

About the front matter

The frontmatter is the material at the beginning of the file, encapsulated between two sets of dashes --- and ---. It is typeset in yaml whereas the body is in markdown, though it will also understand HTML. You don't need to know this, but now you do - this is simply how Jekyll works and it does give us some freedom and power in formatting the pages.

The content of the front matter, for member pages, is a set of variable assignments, such as first_name: Simon F., a key/value pair in yaml lingo. The key's value can be accessed from other pages, e.g. when generating the overview page of all members sorted by affiliation - done by two for-loops, one over affiliation the other over the names of members having that affiliation; that page is not hand-curated. As a side-note, the language used for looping, sorting, grouping etc. is liquid and again you don't need to know this for editing the content of your own page.

The city attribute

The city attribute is used to generate the map on the members page. The github.io pages do not support _plugins for security reasons and unfortunately generating the members map can therefore not not be implemented in a fully automatic way. So if a new city is defined in the frontmatter (new value for the attribute city), that has not been previously on the map, it has to be added by ONE of the two following ways:

• Manually edit member-locations.js and add it to the hash
• Execute the member-cities.rb in your local repository, check the output member-locations.js and then push your commits or create a pull request.

About tags and categories

In the front matter, we currently (as of [2021-05-04 Tue]) have two special variables named tags and categories (they have a special meaning in blog posts). The idea is to use these, or other variables, to help identify areas of expertise and interest for members. So, for example, if you wanted to know which of your colleagues are knowledgable about dask or qupath you would be able to filter for this with a click or two.

This functionality has not been implemented yet - if you want to contribute, this could be it 😉

Navigation bars

There are several possible navigation bars, read the documentation for whatever Jekyll theme we are using, e.g. minimal-mistakes. Pages are added to the top bar by editing the file navigation.yml in the /_data folder.

The configuration file

Most configuration takes place in the _config.yml file at root level. Be careful if editing this!

Layouts

Instead of specifying and formatting the looks of each individual page, templates are applied: In the /_layouts folder, many are available, often inheriting features from each other, and you can add more if you want. The layout applied to a given file/page is either specified in the YAML frontmatter or applies to all files in a given folder as specified in the configuration file _config.yml. For example, all files in the folders /_pages and /_members have the single layout applied to them.