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 contributing to the knowledge base, you should have
☑️ a GitHub account and some routine with GitHub
☑️ an up-to-date version of Node.JS installed
☑️ an up-to-date version of .NET installed
💡 We recommend working with VS Code, with extensions for easy markdown editing and spell check.
💡 For a general introduction to writing markdown, see the markdown tutorial and references therein.
🚀 Feel free to contact us for Data Steward support.
The DataPLANT Knowledge Base is built on nfdi-web-components which fit markdown content into this "framework".
Please follow these steps to fork the knowledge base repository and clone your fork to your computer.
Fork the Knowledge Base Git repository.
You can work and make any changes in your own repository and commit + push them to your fork.
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.
If edited or added existing content, please assign the original author during your pull-request to review your changes.
author // github
⚠️ This is not a full-fledged GitHub tutorial. Please refer to available tutorials online or contact the Knowledge Base curators.
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.
dotnet tool restorein root directory.
dotnet paket installin root directory.
npm installin root directory.
💡 This needs to be done only once after cloning the repo.
npm run fornax.
This will update the npm package
nfdi4plants/web-components to latest, as well as update the nuget dependency
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.
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).
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.
src/docsstructure (as of July 17th, 2023) looks like this
💡 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).
MUST) attribute in metadata block
Every markdown document with the YAML key
layout: docs stored in
/nfdi4plants.knowledgebase/src/docs or any subfolder
_ignored) will be rendered to html and become publicly available once pushed to the main repository.
_ignoredwill not be used to generate html pages.
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
add sidebar: _sidebars/mainSidebar.md)
.mdfile 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 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
Published they will be accessed by
In the following, some ideas are described on how to deal with this:
Basic relative paths:
A basic relative path looks like this:
By starting with
/ we implicitly say "start at host".
In development the same path will start with
http://127.0.0.1:8080/, in production it will start with
In production we also use
Relative paths in sidebar:
The sidebars actually checks if you are currently in
npm run fornax mode.
Therefore, you can use basic relative paths for this. (mainSidebar.md)
/docs/fundamentals/index.html will be parsed to
Relative paths from current file:
These might be easier to handle but need more maintenance as they MUST be changed when the folder/file structure changes, but they circumvent the basepath issue of "Basic relative paths". Examples:
[Test](./ResearchDataManagement.html). Starting with
./translates to "coming from the position of this file".
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
Images can be linked
💡 Please store images in
src/docs/imgholds image files (preferably *.svg, *.png) or the original source file (.pptx, .drawio.svg) used to create the image file(s).
src/docs/imgis supposed to be a file of only a single slide or slide sequence (i.e. consecutive slides, where one image builds on the previous)
title: Data Management Plan
⚠️ Changing file names (and paths) means changing URLs and can easily lead to 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:
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
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://nfdi4plants.org/nfdi4plants.knowledgebase/, rather than a concrete link to a tutorial (e.g. https://nfdi4plants.org/nfdi4plants.knowledgebase/docs/guides/arcCommander_QuickStart.html).
We generally try to address users and readers directly. Use "you can", not "the user can" or "one can..."
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.