Home Fundamentals Research Data Management FAIR Data Principles Metadata Ontologies Data Sharing Data Publications Data Management Plan Version Control & Git Public Data Repositories Persistent Identifiers Electronic Lab Notebooks (ELN) DataPLANT Implementations Annotated Research Context User Journey ARC specification ARC Commander QuickStart QuickStart (Experts) Swate QuickStart Walk-through Best Practices For Data Annotation DataHUB DataPLAN Ontology Service Landscape ARC Commander Manual Setup Git Installation ARC Commander Installation Windows MacOS Linux ARC Commander DataHUB Access Before we start Central Functions Initialize Clone Connect Synchronize Configure Branch ISA Metadata Functions ISA Metadata Investigation Study Assay Update Export ARCitect Manual Installation - Windows Installation - macOS Installation - Linux QuickStart QuickStart - Videos ARCmanager Manual What is the ARCmanager? How to use the ARCmanager Swate Manual Annotation tables Building blocks Building Block Types Adding a Building Block Filling cells with ontology terms Advanced Term Search File Picker Templates Contribute Templates ISA-JSON DataHUB Manual Overview User Settings Generate a Personal Access Token (PAT) Projects Panel ARC Panel Forks Working with files ARC Settings ARC Wiki Groups Panel Create a new user group Data publications Passing Continuous Quality Control Submitting ARCs with ARChigator Track publication status Use your DOIs Guides ARC User Journey Create your ARC ARC Commander QuickStart ARC Commander QuickStart (Experts) ARCitect QuickStart Annotate Data in your ARC Annotation Principles ISA File Types Best Practices For Data Annotation Swate QuickStart Swate Walk-through Share your ARC Register at the DataHUB DataPLANT account Invite collaborators to your ARC Sharing ARCs via the DataHUB Work with your ARC Using ARCs with Galaxy Computational Workflows CWL Introduction CWL runner installation CWL Examples CWL Metadata Recommended ARC practices Syncing recommendation Keep files from syncing to the DataHUB Working with large data files Adding external data to the ARC ARCs in Enabling Platforms Publication to ARC Troubleshooting Git Troubleshooting Contribute Swate Templates Knowledge Base Teaching Materials Events 2023 Nov: CEPLAS PhD Module Oct: CSCS CEPLAS Start Your ARC Sept: MibiNet CEPLAS Start Your ARC July: RPTU Summer School on RDM July: Data Steward Circle May: CEPLAS Start Your ARC Series Start Your ARC Series - Videos Events 2024 CEPLAS ARC Trainings – Spring 2024 MibiNet CEPLAS DataPLANT Tool-Workshops Frequently Asked Questions

Knowledge Base Contribution Guide

last updated at 2023-07-19 About this guide

Your contribution to the DataPLANT Knowledge Base is highly appreciated. This guide is intended to show you how to contribute new articles and tutorials or review and adapt parts of existing ones. For changes and suggestions, feel free to open a GitHub issue or pull request.

UserData Steward ModeTutorial

Before we start

Before contributing to the knowledge base, you should have


Introduction

The DataPLANT Knowledge Base is built on nfdi-web-components which fit markdown content into this "framework".

GitHub Routines

Please follow these steps to fork the knowledge base repository and clone your fork to your computer.

  1. Fork the Knowledge Base Git repository.

    • This creates a copy of the Knowledge Base repository in your own GitHub account.
    • In the top left, you will see that the repository is associated with your account (1) and forked from the main repository (2).
    • You can either directly add or edit content using GitHub or clone (3) your repository to work on it locally.
    • Be aware that your fork is not automatically updated, if the main repository updates. Make sure to update your fork regularly (especially before creating new content) by clicking "Fetch upstream" (4) in the top-right corner of your repository.
    • If you cloned your repository locally, you also have to update the local clone (via "git pull").

Git Routine

  1. You can work and make any changes in your own repository and commit + push them to your fork.

  2. Once you want to submit those changes to the main repository, you can open a "pull request" by clicking "Contribute" (5) in the top-right corner.

    Remember to "Fetch upstream" (4), if your fork is not up-to-date with the main repository.

  3. If edited or added existing content, please assign the original author during your pull-request to review your changes.

⚠️ This is not a full-fledged GitHub tutorial. Please refer to available tutorials online or contact the Knowledge Base curators.

Local testing

The following instructions allow you to test and see how your changes come into play and check whether everything renders correctly.

⚠️ It's highly recommended to frequently check your changes locally. Please do not produce and submit a lot of content without prior local testing.

Setup
  1. Download the repo.
  2. Run dotnet tool restore in root directory.
  3. Run dotnet paket install in root directory.
  4. Run npm install in root directory.

💡 This needs to be done only once after cloning the repo.

Run
  1. Run npm run fornax.
  2. Open the page in your browser http://127.0.0.1:8080/.
Routines Update Dependencies

This will update the npm package nfdi4plants/web-components to latest, as well as update the nuget dependency Nfdi4Plants.Fornax to latest. Then it will bundle all npm (javascript) dependencies to a single bundle.js file with rollup.

npm run updatecomponents Bundle Npm Dependencies

This is part of the execution chain of npm run updatecomponents

npm run bundle Update Searchbar Index

Index created html files. Creates src/_public/pagefind folder. MUST be used after running npm run fornax at least once. Otherwise there will be no .html files to index.

npm run index

Same as npm run index but starts local server to test search bar. Currently the only way to test search bar locally, but will not allow to track changes in markdown files like npm run fornax does (If you want to combine both a PR would be more than welcome).

npm run indexserve
Authoring Content

Read more about authoring content in the fornax section of the nfdi4plants web components docs

⚠️ Please make sure to especially follow the markdown syntax section.

💡 The following sections refer to contents with layout: docs as used for articles and guides.

🚧 Contribution of slides (i.e. in folder src/docs/teaching-materials/ and sidebar section "Teaching Materials") is currently under construction. See the additional guide on slide decks.

Knowledge Base repo structure src/docs ├── _ignored ├── _sidebars ├── ArcCommanderManual ├── DataHUB-Manual ├── faqs │ └── faqs.md ├── fundamentals │ ├── DataManagementPlan.md │ ├── DataPublications.md │ ├── ... ├── guides │ ├── ARCUserJourney.md │ ├── BestPracticesForDataAnnotation.md │ ├── ... ├── img ├── implementation │ ├── AnnotatedResearchContext.md │ ├── AnnotationPatterns.md │ ├── ArcCommander.md │ ├── ... ├── SwateManual ├── teaching-materials ├── tutorials ├── CONTRIBUTING.md └── Home.md

💡 For easier findability, we try to align the folder structure with how the content is presented in the sidebar of the public site. However, this is not always feasible or sensible (for reasons).

Common Errors Markdown to HTML Rendering Rules

Every markdown document with the YAML key layout: docs stored in /nfdi4plants.knowledgebase/src/docs or any subfolder (except _ignored) will be rendered to html and become publicly available once pushed to the main repository.

Ignored Content Visible or Hidden

Although most markdown content will be rendered and published, it will not prominently be visible to all visitors. It will only become visible in the sidebar once the article is linked in the respective sidebar (typically add sidebar: _sidebars/mainSidebar.md)


Content Design Principles References Relative Paths

We SHOULD always try to use relative paths, as they are easier to maintain.
Although useful, they need a bit more fine tuning for different purposes.

Relative paths in production are differently accessed than in development. One of the major issues with relative paths is that during development the pages are accessed by /, for example /docs/README.html. Published they will be accessed by /nfdi4plants.knowledgebase (/nfdi4plants.knowledgebase/docs/README.html). In the following, some ideas are described on how to deal with this:

Document structure and format

Try to avoid deep structures by using no more than two headline levels, i.e.

```
## Headline level 2
### Headline level 3
```

Headline level 1 is automatically generated from the article's title: .

Images / figures

Images can be linked

  1. via simple markdown logic: ![name_of_image](path_to_image.png)
  2. via html: <img src="path_to_image.png">

💡 Please store images in src/docs/img.

Licensed material
File Name Requirements

File names:

⚠️ Changing file names (and paths) means changing URLs and can easily lead to dead links.

Avoiding dead links

Once in a while, we (need to) restructure the /nfdi4plants.knowledgebase/src/docs folder a bit, which includes changes to file and folder names, i.e. producing dead links. In this case, the least we can do, is to keep the knowledge base itself intact:

  1. Carefully check all markdown documents for cross-links to the original file name (this can easily be done via e.g. VS Code).
  2. Remember to check for both file endings .md and .html.
  3. Replace with the new file name / path.

This however does not help for articles, tutorials, etc. that have been shared with the community (via mail, in slide decks, etc.). In this case, please leave a markdown with the original file name and path and just fill it with the following

--- layout: docs date: 2023-06-07 status: prevent-dead-link title: Sorry, this site moved... --- The site you are looking for was moved [here](./../path/to/new/file).

This is not the most beautiful solution as it clutters the knowledge base, but it helps against user frustration and should be done for frequently shared articles. Adding a date helps us clean up those files after a certain time interval.

💡 If you're sharing content with the users, it might be best to only share the link to the knowledge base https://www.nfdi4plants.de/nfdi4plants.knowledgebase/, rather than a concrete link to a tutorial (e.g. https://www.nfdi4plants.de/nfdi4plants.knowledgebase/docs/guides/arcCommander_QuickStart.html).

Addressing Readers

We generally try to address users and readers directly. Use "you can", not "the user can" or "one can..."

Language

British English

Note: If you work with Visual Studio Code - Check out the extension "Code Spell Checker" https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker with British English ("cSpell.language": "en-GB") support.

DataPLANT Support

Besides these technical solutions, DataPLANT supports you with community-engaged data stewardship. For further assistance, feel free to reach out via our helpdesk or by contacting us directly .
Contribution Guide 📖
✏️ Edit this page