Difficulty level: moderate
Reading time: 30 minutes
FAIR Cookbook Contributors
Recipe Type: Hands on
Executable code: No
This document aims to guide users through the process of getting set up to contribute content to the the FAIR cookbok 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.
At the current time, the
HackMD-it browser extension is only available for Chrome and Firefox and this tutorial details the installation procedure.
Once you've carried the extension installation, any github repository for which you have access and for which HackMD app has been authorized (which is already the case for all FAIRplus github repositories), any
Markdown document will be readily editable using 'HackMD' and you should see the following icon
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.
2. Create a github account and obtain your github handle (e.g. @proccaserra)
3. Request to be added to the FAIR Cookbook github repository and accept the invitation.
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
git checkout -b recipe_xx master
6. create a HackMD.io account, simply using your github credentials
Here is a good tutorial provided by Gitlab
use the split view to have what you type immediately rendered.
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.
- 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 an new recipe, you first need to create
my_new_recipe.md file under a branch of the FAIRcookbook 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
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.
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 will lose any changes made during the editing phase.
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
- Directly from HackMD by creating a new note from the tool itself
To do so, open HackMD and go the
This will open a 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 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:
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
This recipe should get you started to contribute content, writing markdown documents, following the FAIRplus guidance and FAIRplus recipe template.
|Philippe Rocca-Serra||University of Oxford, Data Readiness Group||0000-0001-9853-5668||Writing - Original Draft|
|Susanna-Assunta Sansone||University of Oxford, Data Readiness Group||0000-0001-5306-5690||Writing - Review & Editing, Funding acquisition|
This page is released under the Creative Commons 4.0 BY license.