Session 16 : Markdown : écris des notes qui ressemblent au web

Tu connais peut-être HTML par internet : <h1>, <p>, <a>. Mais pour des notes et de la documentation, HTML demande beaucoup trop de frappe. C’est pour ça que Markdown existe.

Markdown est un mini-langage que tu écris en texte normal. Ça reste lisible sans devoir d’abord le convertir. Et d’une seule pression sur un bouton, ça devient du HTML propre : des titres, des listes, des liens, des tableaux.

Dans cette session, tu apprends toute la base de Markdown. À la fin, tu écriras des notes qui ont l’air professionnelles, sur GitHub, dans Obsidian, ou dans n’importe quel autre programme qui comprend Markdown.

Ce que tu vas apprendre aujourd’hui

  • Faire des titres et des paragraphes
  • Mettre en forme du texte : gras, italique, barré
  • Les listes et les énumérations
  • Des liens vers d’autres pages et des sites web
  • Insérer des images
  • Faire des tableaux
  • Des lignes horizontales et des blocs de code

Pourquoi Markdown ?

Markdown est partout :

  • GitHub : chaque repo a un README.md en Markdown. Les issues, les pull requests, les wikis : tout est en Markdown.
  • Obsidian, Joplin, Logseq : des applis de notes qui enregistrent tes documents comme fichiers .md.
  • Discord, Slack, Reddit : ils supportent Markdown pour mettre en forme vite fait tes messages.
  • Hugo (ce site !) : toutes les pages de session que tu vois ici sont écrites en Markdown.
  • Jupyter Notebooks : les cellules de texte sont en Markdown.

Le grand avantage : tu écris du texte normal. Pas de tags compliqués. Et le résultat reste toujours lisible, même en texte brut.

Étape 0 : Créer un fichier Markdown

Les fichiers Markdown se terminent par .md. Crée-en un :

mkdir mijn-notities
cd mijn-notities
echo "# Ma première note" > test.md

Tu peux ouvrir des fichiers .md dans n’importe quel éditeur de texte : le Bloc-notes, VS Code, Thonny, Obsidian. VS Code a une preview intégrée : clique en haut à droite sur l’icône avec la loupe et le livre.

Étape 1 : Titres et paragraphes

Tu fais des titres avec #. Plus il y a de #, plus le titre est petit :

# Ceci est un titre (h1)

## Ceci est un sous-titre (h2)

### Ceci est un titre plus petit (h3)

#### Encore plus petit (h4)

Tu fais un paragraphe en tapant simplement du texte. Une ligne vide entre les deux commence un nouveau paragraphe :

Ceci est le premier paragraphe. Il continue comme ça.

Ceci est le deuxième paragraphe. Parce qu'il y a une ligne vide entre les deux.

Astuce : tu n’utilises # qu’une seule fois par document : pour le titre. Le reste commence à ##.

Étape 2 : Mettre en forme du texte

**Ceci est en gras**

*Ceci est en italique*

~~Ceci est barré~~

Tu peux aussi **mettre du *gras* et de l'italique ensemble** dans la même phrase.

Le résultat :

  • **gras** devient gras
  • *italique* devient italique
  • ~~barré~~ devient barré

Attention : pas d’espaces entre les astérisques et le texte. ** gras ** ne marche pas. **gras** oui.

Certains éditeurs acceptent aussi les underscores : __gras__ et _italique_. Mais les astérisques sont le standard : utilise-les.

Étape 3 : Lignes horizontales

Tu fais une ligne horizontale avec trois tirets (ou plus) :

---

Ou avec des astérisques :

***

Le résultat est une ligne sur toute la largeur. Utilise-le avec parcimonie : une ou deux par document, c’est assez. Trop de lignes rendent tes notes brouillonnes.

Étape 4 : Listes

Liste non numérotée

Utilise -, * ou + :

- Python
- Git
- Markdown
- GitHub

Tu peux imbriquer des listes en indentant (2 ou 4 espaces) :

- Langages de programmation
  - Python
  - JavaScript
- Gestion de versions
  - Git
  - GitHub

Liste numérotée

1. Ouvre Thonny
2. Écris ton code
3. Clique sur Run

Peu importe les numéros que tu tapes : Markdown numérote automatiquement. Ceci :

1. Étape un
1. Étape deux
1. Étape trois

…donne exactement le même résultat que 1, 2, 3. Pratique si tu veux ajouter une étape plus tard sans tout renuméroter.

Checklist (style GitHub)

- [x] Installer Git
- [x] Faire ton premier commit
- [ ] Apprendre les branches
- [ ] Ouvrir une pull request

[x] est coché, [ ] est ouvert. Ça marche dans les issues GitHub, les pull requests, et beaucoup d’applis de notes.

Étape 5 : Liens

Liens externes (vers des sites web)

[clique ici pour le site CoderDojo](https://python.coderdojohasselt.be)

Le mot entre [ ] est le texte cliquable. L’URL entre ( ) est la destination.

Liens internes (vers d’autres pages de ton projet)

[Voir la session 11](11-git-intro/)

Ça fait un lien vers le fichier 11-git-intro/_index.md dans le même dossier.

Lien rapide (montre l’URL directement)

<https://github.com>

Ça montre l’URL comme lien cliquable, sans texte séparé.

Étape 6 : Images

Une image, c’est presque la même chose qu’un lien, mais avec un ! devant :

![Une étoile dans Pygame Zero](/sessions/01-catch-the-stars/coordinaten.svg)

Le texte entre [ ] est le texte alt : il apparaît si l’image ne charge pas, ou il est lu par les screen readers.

Images et Git : Les petites images (SVG, petits PNG), tu peux les mettre dans Git. Les grosses images (>1 MB) et les vidéos, mieux vaut éviter, parce qu’elles ralentissent ton repo.

Étape 7 : Tableaux

| Commande | Ce qu'elle fait |
|----------|-------------|
| `git init` | Créer un nouveau dépôt |
| `git add` | Préparer des fichiers pour le commit |
| `git commit` | Enregistrer les modifications |
| `git push` | Envoyer les commits vers GitHub |

Les caractères | forment les colonnes. La ligne --- sépare l’en-tête des données. Le : dans la ligne de séparation détermine l’alignement :

| Aligné à gauche | Centré | Aligné à droite |
|:-----------------|:-----------:|------------------:|
| gauche           | milieu      | droite            |

Étape 8 : Code et blocs de code

Code inline

Utilise des backticks pour de courts bouts de code dans une phrase :

Utilise `git status` pour voir ce qui a changé.

Blocs de code

Pour plusieurs lignes de code, tu utilises trois backticks :

```python
def groet(naam):
    return f"Hallo {naam}!"
```

La langue (python) derrière les premiers backticks donne du syntax highlighting. Ça marche pour des dizaines de langues : bash, html, css, javascript, json, yaml, markdown.

Bloc de code sans langue

```
Ceci est juste du texte
sans syntax highlighting
```

Étape 9 : Blockquotes

Utilise > pour des citations ou des remarques importantes :

> Git n'est pas un back-up. Git est une machine à remonter le temps.
> Quelqu'un sur internet

Plusieurs lignes > à la suite forment un seul bloc. Une ligne > vide commence un nouveau paragraphe à l’intérieur de la citation.

Étape 10 : Tout ensemble : un vrai README

Un bon README.md combine tout ce que tu connais maintenant. Voici un exemple :

# Mon projet

Une courte description de ce que fait ce projet.

## Installation

```bash
git clone https://github.com/jouw-naam/mijn-project.git
cd mijn-project
```

## Utilisation

1. Ouvre `main.py` dans Thonny.
2. Clique sur **Run**.
3. Choisis un niveau et démarre.

## Ce que tu apprends

- [x] Bases de Pygame Zero
- [x] Collision detection
- [ ] Système de highscore
- [ ] Effets sonores

## Liens

- [CoderDojo Hasselt](https://coderdojohasselt.be)
- [Code source sur GitHub](https://github.com/jouw-naam/mijn-project)

Cheatsheet

QuoiMarkdown
Titre niveau 1# Titre
Titre niveau 2## Sous-titre
Titre niveau 3### Titre plus petit
Gras**gras**
Italique*italique*
Barré~~barré~~
Ligne horizontale--- ou ***
Liste (non ordonnée)- item
Liste (numérotée)1. item
Checklist- [ ] item ouvert
Lien[texte](url)
Image![texte alt](url)
Code inline`code`
Bloc de code```langue
Citation> citation
Tableau| colonne | colonne |

Showcase

Montre à un coach et à un buddy :

  1. Un document Markdown avec au moins un titre, une liste, un lien et du texte en gras.
  2. Un tableau avec au moins deux colonnes et trois lignes.
  3. Une checklist avec des items cochés et des items ouverts.

À la prochaine !

Markdown est simple, mais il est partout. Tes README sur GitHub, tes notes dans Obsidian, ta documentation : tout devient plus lisible avec Markdown. Utilise-le. N’en fais pas trop avec la mise en forme. De bonnes notes sont claires, pas chargées.

À emporter chez toi

  1. Facile : écris un README.md pour ton projet Python préféré. Utilise des titres, une liste et un bloc de code.
  2. Moyen : fais une note dans Obsidian (ou un autre éditeur Markdown) sur ce que tu as appris ce mois-ci. Utilise toute la mise en forme du cheatsheet au moins une fois.
  3. Difficile : construis une page « cheatsheet » en Markdown pour un sujet de ton choix (commandes Git, syntaxe Python, formules de maths). Utilise des tableaux et des listes imbriquées.
  4. Très difficile : fais un document Markdown avec une liste imbriquée qui va au moins sur trois niveaux de profondeur, un tableau avec de l’alignement, et un bloc de code avec du syntax highlighting.