# Ajouter un cours

Cette page explique comment ajouter un cours à ce site. Le site est construit avec [Récit](https://recit.dev) : on écrit des fichiers Markdown, et le menu se construit tout seul depuis les dossiers.

## Où ranger les fichiers

Les pages sont dans `pages/`, les présentations dans `decks/`.

```text
pages/
├── index.mdx                      la page d'accueil
├── presentations.mdx
├── ajouter-un-cours.mdx
└── terminal/                      un dossier par thème
    ├── index.mdx                  l'accueil du thème
    ├── 10-cli/                    un dossier par cours
    ├── 20-gestionnaires-de-paquets/
    ├── 30-git/
    │   ├── index.mdx              la vue d'ensemble du cours
    │   ├── 10-trois-zones.mdx     une page par notion
    │   ├── 20-commits.mdx
    │   ├── 30-branches.mdx
    │   ├── 40-depot-distant.mdx
    │   ├── 50-revenir-en-arriere.mdx
    │   └── 90-exercices.mdx       à retenir et exercices
    └── 40-ssh/
decks/
├── recit.config.json              les réglages communs des présentations
└── terminal.md                    une présentation par thème
```

Trois règles :

- **Un dossier par cours, une page par notion.** Une page courte se lit d'une traite et se retrouve dans le menu.
- **Un `index.mdx` dans chaque dossier.** Un dossier sans `index.mdx` n'apparaît pas dans le menu.
- **Un préfixe numérique pour l'ordre.** `10-`, `20-`, `30-` : on numérote de dix en dix pour pouvoir intercaler une page plus tard.

Les noms sont en minuscules, sans accent, avec des tirets à la place des espaces.

### L'adresse d'une page

Le préfixe numérique disparaît de l'adresse.

| Fichier | Adresse |
| --- | --- |
| `pages/terminal/index.mdx` | `/terminal` |
| `pages/terminal/30-git/index.mdx` | `/terminal/git` |
| `pages/terminal/30-git/30-branches.mdx` | `/terminal/git/branches` |
| `decks/terminal.md` | `/presentations/terminal` |

## Ajouter un cours à un thème

<Stepper>

1. **Créer le dossier du cours** dans le thème, avec son préfixe : `pages/algorithmes/30-tri/`.

1. **Écrire `index.mdx`**, la vue d'ensemble : le problème et le plan du cours.

1. **Écrire une page par notion**, puis `90-exercices.mdx`.

1. **Vérifier** avec `pnpm dev`, puis `pnpm build` avant de partager.

</Stepper>

Il n'y a rien à déclarer : le cours apparaît dans le menu du thème, à la place que lui donne son préfixe.

### Le modèle de vue d'ensemble

À copier dans `index.mdx`.

````mdx
---
title: Titre du cours
section_label: Titre court pour le menu
sidebar_label: Vue d'ensemble
sidebar_icon: book-open
description: Une phrase qui dit ce qu'on apprend.
---

Une ou deux phrases : à quoi sert cette notion.

## Le problème

Un extrait du jeu, ou une situation concrète, qui montre pourquoi on en a besoin.

## Le plan du cours

| Page | Ce qu'on y apprend |
| --- | --- |
| [Première notion](/theme/cours/premiere-notion) | … |
| [À retenir et exercices](/theme/cours/exercices) | Le résumé du cours et les exercices |
````

### Le modèle de page

À copier dans `10-premiere-notion.mdx`.

````mdx
---
title: Ce qu'on apprend sur cette page
sidebar_icon: layers
description: Une phrase de résumé.
---

Une phrase d'introduction : la page doit pouvoir se lire seule.

## La notion

L'explication, avec un schéma si ça aide.

```mermaid
flowchart LR
    A[Avant] --> B[Après]
```

## Dans le jeu

```python
# un extrait de code réel du projet
```
````

La dernière page, `90-exercices.mdx`, contient deux sections : `## À retenir` et `## Exercices`.

## L'en-tête d'une page

Les lignes entre `---` en haut du fichier configurent la page.

| Champ | Rôle | Exemple |
| --- | --- | --- |
| `title` | Titre de la page et libellé dans le menu | `Les requêtes SQL` |
| `sidebar_icon` | Icône dans le menu | `database` |
| `description` | Résumé, utilisé par la recherche | `Lire et filtrer des données.` |
| `sidebar_label` | Libellé plus court pour le menu, facultatif | `Requêtes` |
| `section_label` | Dans un `index.mdx` : le nom du dossier dans le menu | `Bases de données` |

Les icônes viennent de [Lucide](https://lucide.dev/icons). On copie le nom affiché sous l'icône, en minuscules avec des tirets.

| Thème | Icônes qui conviennent |
| --- | --- |
| Ligne de commande | `terminal` |
| Docker | `container`, `package` |
| Git | `git-branch` |
| Web | `code-xml`, `palette`, `atom` |
| Tests | `flask-conical` |
| Algorithmes | `binary`, `route` |
| Données | `database` |
| Exercices | `dumbbell` |

## Ajouter un thème

Un thème est un dossier de `pages/` avec son `index.mdx`. Pour les bases de données, par exemple : `pages/bases-de-donnees/index.mdx`, puis un dossier par cours.

C'est la seule opération qui demande de toucher à la configuration. Dans `recit.config.ts`, on ajoute le dossier à l'onglet voulu :

```ts
{
  type: "category",
  label: "Programmation",
  icon: "code",
  items: [
    { ...theme("python"), label: "Python", icon: "list-checks" },
    { ...theme("algorithmes"), label: "Algorithmes", icon: "binary" },
    { ...theme("bases-de-donnees"), label: "Bases de données", icon: "database" },
  ],
},
```

On ajoute aussi une ligne au tableau des cours de [la page d'accueil](/).

## Ce qu'on peut mettre dans une page

### Texte, tableaux, code

La syntaxe est celle de Markdown. Les blocs de code prennent le nom du langage pour la coloration : `python`, `bash`, `tsx`, `dockerfile`, `text`.

### Encadrés

```md
:::tip{title="Astuce"}

Le texte de l'encadré.

:::
```

Cinq types existent : `note`, `tip`, `info`, `caution`, `danger`. La ligne d'ouverture et la ligne de fermeture sont seules sur leur ligne, avec une ligne vide après l'une et avant l'autre.

:::tip{title="Astuce"}

Un encadré attire l'œil. S'il y en a trois par page, plus aucun ne ressort.

:::

### Schémas

Un bloc de code `mermaid` est dessiné comme un schéma, sans rien importer. Voir [Les schémas Mermaid](/documentation/mermaid).

### Étapes numérotées

```md
<Stepper>

1. **Première étape.** Explication.

1. **Deuxième étape.** Explication.

</Stepper>
```

### Une présentation dans une page

`<StoryEmbed slug="terminal" />` affiche la présentation `decks/terminal.md`. Avec `slide={4}`, elle s'ouvre sur la quatrième diapositive.

## Les pièges du format MDX

Un fichier `.mdx` mélange Markdown et composants. Deux caractères ont un sens spécial **en dehors des blocs de code** :

| Caractère | Problème | Solution |
| --- | --- | --- |
| Accolade ouvrante ou fermante | Lue comme du JavaScript | La mettre entre accents graves, comme du code |
| Chevron ouvrant | Lu comme le début d'une balise | Écrire « inférieur à », ou le mettre entre accents graves |

Quand une page est cassée, `pnpm build` indique le fichier et la ligne.

## Écrire une présentation

Une présentation est un fichier Markdown de `decks/`. Chaque diapositive commence par une ligne `---`, qui peut porter sa mise en page.

````md
---
title: Bases de données
description: "Tables, requêtes et SQLite."
lang: fr
duration: 20
---

--- layout=cover id=couverture

# Bases de données

--- id=probleme

# Les scores disparaissent au redémarrage

:::callout{type=warning title="Le problème"}
Tout est gardé en mémoire : rien ne survit à l'arrêt du programme.
:::

:::notes
Ce que l'intervenant dit, en phrases complètes.
:::
````

| Élément | Syntaxe |
| --- | --- |
| Mise en page | `--- layout=cover`, `section`, `center`, `grid cols=3`, `columns`, `split` |
| Carte d'une grille | `:::card` |
| Apparition progressive | `:::step` |
| Encadré | `:::callout{type=tip title="…"}` |
| Notes de l'intervenant | `:::notes` |
| Schéma | Un bloc `mermaid`, avec `title="…"` |

Une diapositive se lit de loin. Le site refuse donc une diapositive trop chargée : **40 mots, 6 puces, 4 cartes, 3 colonnes** au plus. Ce qui ne tient pas va dans les notes.

```bash
pnpm decks:check                      # vérifie toutes les présentations
pnpm exec recit dev decks/terminal.md # en affiche une, avec rechargement à chaud
```

Une présentation rangée dans `decks/` est publiée sans rien déclarer. On l'ajoute à la liste de la page [Les présentations](/presentations) et à l'accueil de son thème.

## Liste de contrôle avant de publier

- Le titre dit ce qu'on apprend, pas seulement le sujet.
- Le cours commence par le problème, pas par la définition.
- Chaque page se lit seule et tient en un écran ou deux.
- Chaque extrait de code a été exécuté au moins une fois.
- Les liens vers d'autres pages commencent par `/`, sans préfixe numérique ni extension.
- `pnpm decks:check` et `pnpm build` passent sans erreur.
- Le tableau des cours de [la page d'accueil](/) est à jour.
