Contribution to DataPLANT

last updated at 2023-07-25 Data Steward Circle

bg fit

Contribution to DataPLANT July 25th, 2023

Dominik Brilhaus


Knowledge Base

Create, share, reuse, collaborate on

DataPLANT Knowledge Base: https://www.nfdi4plants.de/nfdi4plants.knowledgebase/


Content
Resources

Contents shown here are (in part) already somewhere in the Knowledge Base or at least in the GitHub repo. However, ⚠️ Links there are somewhat volatile ⚠️


Part 1: Setup
Required

☑️ a GitHub account ☑️ Git installed and configured


Recommended software

☑️ GitHub Desktop

☑️ Visual Studio Code


Recommended VS code extensions for markdown
Creating markdown slides in VS code: marp

Marp for VS Code


Part 2: Basics
Markdown

💡 See the Markdown tutorial and references therein


Markdown Slides (with Marp)

💡 See the Marp slide decks tutorial


GitHub

The DataPLANT GitHub organization (https://github.com/nfdi4plants) and repositories are the place where most of the magic (tool development) happens.

💡 Most repositories are public and open for (user) feedback


Issues

💡 See also: https://docs.github.com/en/issues/tracking-your-work-with-issues/quickstart


👩‍💻 Exercise: Open a GitHub issue
  1. Navigate to the Knowledge Base or another DataPLANT repo
  2. Raise an issue, e.g.
    1. raise a question
    2. report a bug
    3. request a feature

Forks and pull requests (PR)

💡 See also: https://docs.github.com/en/get-started/quickstart/fork-a-repo


👩‍💻 Exercise: Fork and clone a GitHub repo
  1. Navigate to the Knowledge Base
  2. Fork the repo (i.e. create a copy under your user name)
  3. Clone your fork locally (to your machine)

w:800px


👩‍💻 Exercise: Create a new article (markdown)
  1. Open your local "Knowledge Base" clone (File explorer or VS Code)
  2. In src/docs/_ignored, create a new text file <YourInitials>_dsc.md
  3. Add the following YAML header:
--- layout: docs title: <YourTitle> author: <YourName> date: 2023-07-25 ---
  1. add some text below the YAML header

👩‍💻 Exercise: Open a pull request
  1. Save your local changes
  2. Sync to your fork
    1. via command line (add, commit, push) or
    2. via VS Code or
    3. via GitHub Desktop
  3. Contribute / open a PR (follow instructions on GitHub)

w:800px


Part 3: The Knowledge Base
Required software

☑️ Node.JS
☑️ .NET

  💡 Both required for local testing of Knowledge Base


Knowledge Base backend: Fornax

w:700px

💡 See nfdi4plants web components docs


Setup
  1. Clone 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.


Knowledge base local test
  1. Run npm run fornax.
  2. Open the page in your browser http://127.0.0.1:8080/.

Let's have a look at your articles (pull-requests)
Markdown syntax
  • MUST start and end with --- .
  • MUST contain layout: docs.
    • This triggers fornax parsing to html.
  • MUST contain title: xxxx.
    • added as "# xxxx" to the html
    • used to name the generated webpage.
  • MUST contain date: yyyy-MM-dd
  • MAY contain author: xxxx.
  • MAY contain add toc: true.
    • If true, adds automated table of contents from all found headers in content.
  • MAY contain add support: true.
    • If true adds DataPlant support component at the bottom.
  • MAY contain add sidebar: relative/path/to/sidebar.md to add the sidebar element to the page.
  • MAY contain any other metadata. The information will be read but will not affect the generated html.
  • Keys (layout, author, etc.) are NOT case sensitive.
  • Fields MAY be in any order.
--- layout: docs title: Metadata date: 2022-05-09 author: FirstName LastName add toc: true add sidebar: _sidebars/mainSidebar.md ---

💡 For details, check


Slide decks – work in progress 🚧

💡 Feel free to create slide decks how and where you need them!


Now it's your turn

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