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.
Sign up for a GitHub account.
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
@<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.
dotnet tool restore
in root directory.dotnet paket install
in root directory.npm install
in root directory.npm run fornax
.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).
MUST
) attribute in metadata blockRead 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.
_ignored
will 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
(typically add sidebar: _sidebars/mainSidebar.md
)
.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 `
/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:
.

File names:
title: Data Management Plan
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.