Documentation

Comment marche ce site, pour les élèves comme pour les curieux qui veulent savoir ce qu'il y a derrière. Il contient aujourd'hui 10 cours et 49 leçons.

1. Utiliser le site

Le site est découpé en cours (HTML & CSS, PHP, SQL, Git & GitHub, Linux, Réseau, C#, Lua, JavaScript, Python), chacun divisé en leçons courtes, à suivre dans l'ordre. Chaque leçon a la même structure :

Les objectifs : ce que tu sauras faire à la fin ;
Le cours, avec des exemples de code à lire et à recopier chez toi ;
L'exercice « À toi de jouer » : tu écris ton code dans l'éditeur, et chaque consigne se coche dès qu'elle est réussie ;
Le quiz : 3 ou 4 questions. Le bouton « Corriger le quiz » montre les bonnes réponses et l'explication de chacune.

Une leçon est terminée quand toutes les consignes de l'exercice sont réussies et qu'au moins la moitié des réponses du quiz sont justes. Elle apparaît alors en vert dans le sommaire, et la barre de progression du cours avance sur la page d'accueil.

Le défi final et les badges

À la fin de chaque cours, un défi final ★ propose un exercice plus long, qui réunit tout ce que le cours a montré, sans nouvelle notion et sans quiz.

quand toutes les leçons d'un cours sont terminées, tu gagnes son badge ;
si tu réussis aussi le défi final, le badge passe en or.

Tes badges s'affichent sur la page d'accueil et en haut de la page de chaque cours. Comme la progression, ils sont enregistrés uniquement dans ton navigateur.

Bloqué ? Sous chaque exercice, « Voir une solution » montre une réponse possible. Essaie d'abord vraiment : on apprend beaucoup plus en cherchant qu'en recopiant. Le bouton « Recommencer » remet l'exercice à zéro.

Raccourcis de l'éditeur : Tab insère deux espaces, Échap sort de l'éditeur pour continuer à naviguer au clavier. Le bouton rond en haut à droite passe en mode clair ou sombre.

2. La correction des exercices

HTML et CSS : le vrai résultat

Ton code est affiché dans un cadre isolé, à droite de l'éditeur, à chaque fois que tu arrêtes de taper. Le site regarde ensuite le résultat, comme le ferait un navigateur : est-ce qu'il y a bien un <h1> ? De quelle couleur s'affiche-t-il vraiment ? Peu importe comment tu l'as écrit (#2f5bd3, rgb(47, 91, 211)…), seul le rendu compte.

SQL : de vraies requêtes, exécutées dans ton navigateur

Tes requêtes SQL sont vraiment exécutées, sur une petite base d'exemple (les tables classes, eleves et notes, visibles sous l'éditeur), et le résultat s'affiche sous forme de tableau. Le bouton « Exécuter » (ou Ctrl + Entrée) relance la requête.

Tout se passe dans ton navigateur, grâce à un petit moteur SQL écrit pour ce site (mini-sql.js). Le serveur ne reçoit jamais ta requête, donc il ne court aucun risque. La base repart de zéro à chaque exécution : tu peux supprimer toutes les lignes sans rien casser.

Le site compare ensuite ton résultat à celui de la solution : peu importe comment tu as écrit la requête, ce sont les lignes obtenues qui comptent.

Limite : ce moteur connaît l'essentiel du SQL des cours (SELECT avec WHERE, JOIN, GROUP BY, HAVING, ORDER BY, LIMIT, les fonctions courantes, INSERT, UPDATE, DELETE, CREATE TABLE, DROP TABLE), mais pas tout ce que sait faire MySQL (pas de sous-requêtes par exemple).

PHP, Git, Linux, Réseau, C#, Lua, JavaScript, Python : la relecture du code

Pour ces cours, le code n'est pas exécuté : faire tourner sur le serveur du code ou des commandes envoyés par n'importe qui serait bien trop dangereux. Il est relu avec des règles (des expressions régulières) qui vérifient qu'il contient les bons éléments, au bon endroit.

Limite : une relecture ne comprend pas tout. Une solution juste mais écrite très différemment peut ne pas être reconnue. Dans ce cas, compare avec la solution proposée, et si tu peux, teste ton code chez toi pour voir s'il fonctionne vraiment.

3. Vie privée

pas de compte, pas d'e-mail, pas de cookie, pas d'outil de statistiques ;
ta progression, tes scores, le code tapé dans les exercices et ton choix de thème sont enregistrés uniquement dans ton navigateur (le « stockage local »), sur ton appareil. Rien n'est envoyé au serveur ;
conséquence : si tu changes d'appareil ou de navigateur, ou si tu vides les données du site, ta progression repart de zéro ;
le serveur garde seulement des journaux techniques (adresse IP, page demandée, date) pour sa sécurité, pendant une durée limitée.

4. Sous le capot

Le site est volontairement simple, pour que son code serve lui aussi d'exemple :

PHP 8.3 sans framework et sans base de données. Les leçons sont de simples fichiers PHP qui renvoient un tableau (titre, texte, exercice, quiz) ;
un fichier public/index.php reçoit toutes les demandes et choisit la page à afficher selon l'adresse (c'est un « routeur ») ;
des vues (vues/*.php) mettent le contenu en page, dans un gabarit commun ;
un seul fichier CSS pour l'apparence, avec les couleurs du mode clair et du mode sombre ;
un fichier JavaScript, cours.js, sans bibliothèque : l'éditeur, l'aperçu, les vérifications, le quiz, la progression et les badges ;
mini-sql.js, le petit moteur SQL des exercices : il découpe la requête en mots, la transforme en arbre, puis l'exécute sur des tableaux JavaScript. Il n'est chargé que sur les leçons SQL.

cours/
├── public/            ce qui est accessible depuis le web
│   ├── index.php      le routeur
│   ├── style.css
│   ├── cours.js
│   ├── mini-sql.js    le moteur SQL des exercices
│   └── polices/, exemples/
├── src/outils.php     petites fonctions (afficher une vue, charger une leçon…)
├── vues/              les gabarits des pages
└── contenu/
    ├── modules.php    la liste des cours et l'ordre des leçons
    ├── html-css/      une leçon = un fichier
    ├── php/
    ├── sql/           avec base.php, la base d'exemple
    └── git/, linux/, reseau/, csharp/, lua/, javascript/, python/

Le site tourne sur un serveur Linux (un VPS) dans un conteneur Docker. Devant lui, le serveur web Caddy gère le HTTPS (le cadenas) et ses certificats automatiquement.

5. Sécurité

Rien à voler : pas de base de données, pas de mot de passe, pas de formulaire ;
le conteneur est verrouillé : système de fichiers en lecture seule, aucun privilège, utilisateur non administrateur, mémoire et nombre de processus limités, et les fonctions PHP capables de lancer des commandes sont désactivées ;
il est séparé des autres sites hébergés sur le même serveur : il n'a accès ni à leurs fichiers ni à leurs données ;
l'aperçu des exercices HTML s'affiche dans un cadre isolé où aucun script ne peut s'exécuter, et une politique de sécurité du contenu (CSP) bloque le chargement de scripts venus d'ailleurs.

6. Ajouter une leçon

Une leçon est un fichier dans contenu/<cours>/. Pour qu'elle apparaisse, on ajoute son nom à la liste lecons du cours dans contenu/modules.php. Le défi final d'un cours est le fichier defi.php du même dossier : même modèle, sans quiz. Voici le modèle :

<?php

return [
    'titre' => 'Titre de la leçon',
    'resume' => 'Une phrase qui dit ce qu\'on va apprendre.',
    'duree' => '15 min',
    'objectifs' => ['Objectif 1', 'Objectif 2', 'Objectif 3'],
    'contenu' => '<h2>…</h2><p>…</p>' . code("SELECT * FROM eleves;", 'sql'),
    'exercice' => [
        'type' => 'code',            // 'apercu' pour HTML/CSS, 'sql' pour SQL
        'consigne' => '<p>Ce qu\'il faut faire.</p>',
        'depart' => '',              // le code déjà présent dans l'éditeur
        'tests' => [
            ['texte' => 'La requête lit la table eleves', 'type' => 'regex',
             'motif' => 'from\\s+eleves', 'drapeaux' => 'i'],
        ],
        'solution' => "SELECT * FROM eleves;",
    ],
    'quiz' => [
        ['question' => 'La question ?', 'choix' => ['Réponse A', 'Réponse B'],
         'bonne' => 1, 'explication' => 'Pourquoi B est juste.'],
    ],
];

Les types de vérifications disponibles :

existe, nombre (avec min), rempli, texte (avec contient) et attribut : présence et contenu d'éléments dans le résultat HTML, avec un sélecteur CSS ;
style : la valeur d'une propriété CSS telle qu'elle s'affiche vraiment ; style-different : une propriété qui n'a pas sa valeur par défaut ;
regex et pas-regex : le code doit (ou ne doit pas) correspondre à une expression régulière ;
pour SQL : sans-erreur (la requête s'exécute), resultat (mêmes lignes que la solution, avec ordre pour exiger le même ordre), table (une table contient les mêmes lignes qu'après la solution) et table-colonnes (une table a bien les colonnes demandées).

Astuce : avant de publier, vérifie que la solution coche toutes les consignes et que le code de départ n'en coche pas toutes.

7. Signaler une erreur

Une faute, une explication pas claire, un exercice qui refuse une bonne réponse ? Écris à skapski.a28@gmail.com en indiquant la leçon concernée. Merci !