Ajouter un cours
Cette page explique comment ajouter un cours à ce site. Le site est construit avec Récit : 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/.
Code
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.mdxdans chaque dossier. Un dossier sansindex.mdxn'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 |
pages/ | /terminal/ |
pages/ | /terminal/ |
decks/ | /presentations/ |
Ajouter un cours à un thème
-
Créer le dossier du cours dans le thème, avec son préfixe :
pages/.algorithmes/ 30- tri/ -
Écrire
index.mdx, la vue d'ensemble : le problème et le plan du cours. -
Écrire une page par notion, puis
90-.exercices. mdx -
Vérifier avec
pnpm dev, puispnpm buildavant de partager.
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
Le modèle de page
À copier dans 10-.
MDX
La dernière page, 90-, 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_ | Libellé plus court pour le menu, facultatif | Requêtes |
section_ | Dans un index.mdx : le nom du dossier dans le menu | Bases de données |
Les icônes viennent de Lucide. 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- |
| 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/, puis un dossier par cours.
C'est la seule opération qui demande de toucher à la configuration. Dans recit., on ajoute le dossier à l'onglet voulu :
TypeScript
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
Markdown
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.
Schémas
Un bloc de code mermaid est dessiné comme un schéma, sans rien importer. Voir Les schémas Mermaid.
Étapes numérotées
Markdown
Une présentation dans une page
<StoryEmbed slug= affiche la présentation decks/. 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.
Markdown
| Élément | Syntaxe |
|---|---|
| Mise en page | --- layout=, section, center, grid cols=3, columns, split |
| Carte d'une grille | :::card |
| Apparition progressive | :::step |
| Encadré | :::callout{type= |
| 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
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 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:etcheck pnpm buildpassent sans erreur.- Le tableau des cours de la page d'accueil est à jour.