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.**
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:
Fig. 3.11 edits with HackMD button from GitHub bar.¶
The HackMD button in-situ from a GitHub repository bar:
Fig. 3.12 FAIRplus GitHub repository.¶
Note
⚡ 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.¶
Fig. 3.13 join FAIRplus Cookbook GitHub.¶
3.4. Create a new recipe¶
3.4.1. Create a new issue in the issue tracker¶
Fig. 3.14 Creating a new recipe.¶
Note
ℹ️ 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¶
Fig. 3.15 Creating a HacKMD account.¶
3.7. Getting familiar with MarkDown¶
Here is a good tutorial provided by Gitlab
Fig. 3.16 Getting familiar with Markdown.¶
3.8. Build confidence using HackMD¶
Fig. 3.17 Getting familiar with 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.
3.10. Writing notes with HackMD.io:¶
From a GitHub repository, by editing an existing Markdown
Note
⚡ 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.
Fig. 3.18 HackMD button.¶
This will launch the HackMD.io editor in a separate tab.
Note
⚡ 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.
Fig. 3.19 hackmd editor .¶
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
Warning
☢️ 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.
Directly from HackMD by creating a new note from the tool itself
To do so, open HackMD and go the New Note
Fig. 3.20 Create new Note with HackMD.¶
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.
Fig. 3.21 Pulling content from GitHub.¶
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:
Fig. 3.22 Pushing to git via HackMD UI-0.¶
Navigate to Versions. This will bring the following window:
Fig. 3.23 Check Versions.¶
Press the blue Push to Github button to bring up the following menu:
Fig. 3.24 Pushing to git via HackMD UI - Choosing a file.¶
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.
Fig. 3.25 Pushing to git via HackMD UI - Creating a new file.¶
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.11.1. What to read next?¶
References
3.12. Authors¶
Authors
Name |
ORCID |
Affiliation |
Type |
ELIXIR Node |
Contribution |
|---|---|---|---|---|---|
University of Oxford |
|
Writing - Review & Editing |
|||
University of Oxford |
|
Writing - Review & Editing |
