Fundamentals Research Data Management FAIR Data Principles Metadata Ontologies Data Sharing Data Publications Data Management Plan Version Control & Git Public Data Repositories Persistent Identifiers Implementation within DataPLANT Annotated Research Context User Journey ARC Commander QuickStart QuickStart (experts) Swate QuickStart Walk-through Best Practices For Data Annotation DataHUB DataPLAN ARC Commander Manual Setup Installing Dependencies Configure Git Installing the ARC Commander Windows MacOS Linux DataHUB Access Before we start Central Functions Initialize Clone Connect Synchronize Configure Branch ISA Metadata Functions ISA Metadata Investigation Study Assay Update Export Swate Manual Setup Installing Swate Browser Desktop, via installer (beta-stage) Desktop, manually (recommended) MacOS Organization-wide Core Features Annotation tables Building blocks Building Block Types Adding a Building Block Using Units with Building Blocks Filling cells with ontology terms Advanced Term Search Templates Contribute Templates File Picker Expert Features ISA-JSON Frequently Asked Questions Teaching Materials DataPLANT Overview Big Picture ARC structure ARC Demo

Knowledge Base Contribution Guide

last updated at 2022-12-14 Contribution 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 an issue or to open a pull request.

Introduction

The DataPLANT Knowledge Base is built on nfdi-web-components which fit markdown content into this "framework". For a general introduction to writing markdown, see: Markdown tutorial and references therein.

GitHub Routines

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

  1. Sign up for a GitHub account.

  2. 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.

Local testing

The following instructions allow you to test and see how your changes come into play and 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

This needs to be done only once after downloading.

  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.
Run
  1. Run npm run fornax.
  2. Open page in 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 searchbar. Currently the only way to test searchbar 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 Common Errors Authoring Content

Read more in the fornax section of the nfdi4plants web components docs here

Markdown to HTML Rendering Rules

Every markdown document 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, as there are several options.

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:

Structure and Format

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

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

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

Images File Name Requirements

File names:

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

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.

Link Collection

Note: This is just a link collection for recurrent use in KB articles Nothing automatized. Just copy/paste.

⚠️ Must be read from markdown, will not be shown in html.

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 .
✏️ Edit this page