Contribute¶

This page explains how you can contribute and what are the rules to write a card.

Which kind of contribution ?¶

Any input is welcomed, whatever your background and scientific topics are

review, comments of the existings cards, provide feedback
suggest new ideas, new guideline topics
write new cards
...

How?¶

Cards are written in markdown language for mkdocs and hosted on a Gitlab project used to generate the website.

To propose a new contribution the simplest way (especially if you don't feel comfortable with git-like tools), is to contact us at

You can also fork our gitlab project and submit a new merge-request including your contributions.

Access to the gitlab project¶

The project is public : https://gricad-gitlab.univ-grenoble-alpes.fr/gt-env-logiciels/sandbox-notecards

Register on the gricad-gitlab platform
Fork the project ( button, top-right on the project page) and add your contribution in this new project
Submit a Merge request

Steps to include a new entry in mkdocs generated pages¶

Create a file some_name.md in docs/cards/en
- some_name must corresponds to the title of your card.
- use lower case for the file name
e.g. a card "How to write a card" is written in the file how-to-write-a-card.md
Write your doc in some_name.md following the detailed instructions below
Optional: create the same file in docs/cards/fr (SAME NAME) with the french version of your page.

That's it! The new entry will be automatically included in the generated website, under "cards"

Writing instructions and conventions¶

Mkdocs is used to generate the site from markdown files. We use the materials theme.

Check the Mkdocs - Writing your dos page for details regarding markdown syntax.

Please read below the conventions and practices specific to our pages.

Basics¶

Here is the minimal and proper content of a card.

# ICON-TYPE Title

**Keywords** : <term:name1>, <term:name2>, word, ...

Optional (but recommended): 

+ tag the kind of card (e.g. "tools", "definition", "good practices" ...)

## Context and objectives

🎯 **What**: a clear and short description of the intent/context of the card.

❓ **Why**: explain the relevance of this page to readers, what they can expect to gain from reading it.

👥 **Audience**: explain who/which people are targeted by this card (beginners, ...).

## 🏁 Prerequisites 

Describe precisely the starting point of this card :

- refer to other cards that must have been taken into account
- list the tools that must be known
- ...

## 💡 Advices and best practices 
Only for technical/goot practices cards

## 🛠️ Recommended Tools

## Other titles ...

## 📚 References

For ICON-TYPE choose among:
- 📖 definitions: the concepts and terms we wish to highlight and detail
- 🧭 overview: a kind of meta/summary-card focusing on a particular topic, providing an introduction to the more technical cards (e.g. about specific tools)
- ⚙️ technical cards: focus on a specific tool, pratice ...
Be short and concise. A card should not be too long else it means it may be better to split it in several parts (cards) ...

Glossary¶

How to add entries in the glossary

Create a new entry in docs/glossary.md, like:

term:name
:   Short description

    Long description (optional)

Anywhere else, to create a link to this entry, use:

This is a reference to <term:name> ...

As a result, you can get:

this is a reference to Container

This will also create a list of all references to the chosen term under the corresponding entry in the glossary.