How to write a card?¶

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¶

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.

# 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

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.

Cards tags¶

To be reviewed and updated

Categories :

Definitions¶

Markdown code

# 📖 Card title

Overview / "head" card¶

# 🗺️ Card title

Technical / Good pratices¶

Markdown code:

# ⚙️ Card title