Aller au contenu
Accueil

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
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.

FichierAdresse
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

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

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

  3. Écrire une page par notion, puis 90-exercices.mdx.

  4. Vérifier avec pnpm dev, puis pnpm build avant 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.

MDXMDX
--- 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.

MDXMDX
--- 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.

ChampRôleExemple
titleTitre de la page et libellé dans le menuLes requêtes SQL
sidebar_iconIcône dans le menudatabase
descriptionRésumé, utilisé par la rechercheLire et filtrer des données.
sidebar_labelLibellé plus court pour le menu, facultatifRequêtes
section_labelDans un index.mdx : le nom du dossier dans le menuBases de données

Les icônes viennent de Lucide. On copie le nom affiché sous l'icône, en minuscules avec des tirets.

ThèmeIcônes qui conviennent
Ligne de commandeterminal
Dockercontainer, package
Gitgit-branch
Webcode-xml, palette, atom
Testsflask-conical
Algorithmesbinary, route
Donnéesdatabase
Exercicesdumbbell

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 :

TypeScriptTypeScript
{ 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

MarkdownMarkdown
:::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.

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.

Étapes numérotées

MarkdownMarkdown
<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èreProblèmeSolution
Accolade ouvrante ou fermanteLue comme du JavaScriptLa mettre entre accents graves, comme du code
Chevron ouvrantLu 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.

MarkdownMarkdown
--- 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émentSyntaxe
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émaUn 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.

TerminalBash
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 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.