Knowledge Base 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.

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.

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").

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

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

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

• The github user name of the original author is stored in the yaml block on top under author_github
• During the pull-request mention the author via @<author_github>.

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.

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.

1. Run npm run fornax.
2. Open page in browser http://127.0.0.1:8080/.

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.

This is part of the execution chain of npm run updatecomponents

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.

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

• Missing metadata block
• Missing or false required (MUST) attribute in metadata block
• Using a layout in metadata block that does not exist
• Wrong links
  • to sidebar elements
  • to images

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

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.

• Anything inside the folder _ignored will not be used to generate html pages.
• This folder is intended for ideas and drafts that
  • should not yet become available in the Knowledge Base
  • should be under version control for discussion and reviewing

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)

• Literature / information references: additional bibliography block below
• External links (tools, sites, platforms): as hyper-link
• Knowledge Base cross-references: relative path to *.md document, BUT replace the .md file extension with .html, as the markdown files are parsed to html.

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:

• Basic relative paths: These will look like this: [Test](/README.html). By starting with / we implicitly say "start at host". So in development it will start with http://127.0.0.1:8080/, in production it will start with https://nfdi4plants.github.io/. Because in production we also need https://nfdi4plants.github.io/nfdi4plants.knowledgebase/, this type of relative paths can create issues! ⚠️

• Relative paths in sidebar: The sidebars actually check if you are currently in dotnet fornax watch mode. So you can use basic relative paths here. Example `

  ```Fundamentals # Introduction:/docs/Home.html ```!

  /docs/Home.html will be parsed to /nfdi4plants.knowledgebase/docs/Home.html.

• Relative paths from current file: These need more maintenance as they MUST be changed when the folder/file structure changes, but they circumvent the basepath issue of "Basic relative paths". Example: [Test](./ResearchDataManagement.html). Starting with ./ translates to "coming from the position of this file". We can even go up in the file hierarchy, like [Test](./../docs/README.html). This translates to "coming from the position of this file, go one folder higher and into the docs directory to find the Introduction there."

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

• simple markdown logic (not HTML): ![name_of_image](path_to_image.png)

File names:

• MUST use the article's title for the filename, e.g.: DataManagementPlan.md → title: Data Management Plan
• MUST NOT contain special characters
• MUST NOT contain spaces
• MUST use snake_case (lower_case_with_underscores) OR PascalCase (UpperCase)

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

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

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.

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