3. Add via HackMD

3.1. Main Objectives

**This document aims to guide users through the process of getting set up to contribute content to the FAIR cookbook using HackMD.io online editor.

The document contains a checklist taking you point by point through the installation process and through the 2 main ways of using HackMD.**


IMPORTANT: Install the HackMD browser extension (Chrome, Firefox)

At the current time, the HackMD-it browser extension is only available for Chrome and Firefox and this tutorial details the installation procedure. Once the extension installed, any Markdown document in any GitHub repository you have access to and for which HackMD app has been authorized (which is already the case for all FAIRplus GitHub repositories) will be readily editable using ‘HackMD’ and you should see the following icon in the relevant menu bar:

The HackMD button in-situ from a GitHub repository bar:


⚡ This button will only be visible from Chrome or Firefox once the HackMD browser extension has been installed.

🐙 This will not be visible from Safari, Brave or Internet Explorer browsers even if you have HackMD activated for your repository.

3.2. Create a GitHub account and obtain your GitHub handle

3.3. Request to be added to the FAIR Cookbook GitHub repository and accept the invitation.

3.4. Create a new recipe

3.4.1. Create a new issue in the issue tracker


ℹ️ remember to assign yourself or a team member to the issue

ℹ️ remember to assign the issue to a milestone

ℹ️ remember to tag the issue with relevant label

3.5. Create a new branch under the FAIR Cookbook GitHub repository using the following command:

> git checkout -b recipe_xx master

3.6. Create a HackMD.io account, simply using your GitHub credentials

3.7. Getting familiar with MarkDown

Here is a good tutorial provided by Gitlab

3.8. Build confidence using HackMD

use the split view to have what you type immediately rendered.

3.9. Use the FAIRplus Recipe Template as guide

The FAIRPlus Cookbook Team is working at establishing a standard layout for easing the creation of a new recipe. The template contains key sections and outlines, which will help boostrap the process.

recipe template

3.10. Writing notes with HackMD.io:

  1. From a GitHub repository, by editing an existing Markdown


⚡ In order to be able to push a change to GitHub from HackMD.io, it is required to first create a placeholder markdown file in the targeted GitHub repository.

For instance, you want to create a new recipe, you first need to create my_new_recipe.md file under a branch of the FAIR Cookbook repository.

touch my_new_recipe.md
git add my_new_recipe.md
git push origin my_recipe_branch

In a browser (one with the hackMD browser extension enabled), navigate to the recipe page on the GitHub repository and click on the hackMD button.

This will launch the HackMD.io editor in a separate tab.


⚡ Toggling back to the GitHub page, notice the following message, which highlights 2 options, one allowing to switch back to the editor view, one allowing to end it.

By pressing Stop Editing, HackMD.io tab closes and the user is taken back to GitHub page. The user is now offered to either commit changes or cancel


☢️ Pressing cancel will lose any changes made during the editing phase.

ℹ️ Pressing commit change offers two options. We strongly recommend using the create a new branch for this commit and start a pull request option when choosing to commit changes. This is good practice and always remember to assign a reviewer and set a milestone when sending the pull request.

  1. Directly from HackMD by creating a new note from the tool itself

To do so, open HackMD and go the New Note

This will open an empty HackMD page and if one presses pull from GitHub, a pop-up will open and allow users to select:

  • a GitHub repository

  • a branch in the repository

  • a file in that branch

Fill in the relevant information (all required) before it is possible to hit the blue pull button.

If the pull is successful, the user can now edit the document.

When the edits are completed, the user can push the file back to GitHub. To do so, one needs to hit the ‘…’ icon in the top right-hand corner of the HackMD menu bar, as show below:

Navigate to Versions. This will bring the following window:

Press the blue Push to Github button to bring up the following menu:

The process is very similar to that described when pulling a file. Except that is now possible to create a branch for the commit, an option we recommend using.

Fill all the necessary information and press the blue Push button.

3.11. Conclusion:

This recipe should get you started to contribute content, writing Markdown documents, following the FAIRplus guidance and FAIRplus recipe template.

If unsure about these steps, contact the FAIRPlus editorial team for assistance, using the dedicated email or via our github issue tracker.

3.12. Authors