Accueil > Numéros thématiques de la revue Adjectif > Numéro thématique 3 de la revue Adjectif
Mon premier site web en MkDocs
Sébastien Hoarau
Laboratoire d’Informatique et de mathématiques, Université de la Réunion
Fabrice Nativel
IREM de la Réunion
Numéro thématique 3 / 2023-T3
RÉSUMÉ À la session 2022 des ateliers Didapro, nous proposions un atelier découverte par la pratique de l’outil mkdocs pour la réalisation d’un site web à destination de l’enseignement. Cet article prolonge l’atelier passé et présente les principales possibilités de cette solution issue de diverses expérimentations d’une communauté d’enseignant•e•s. Nous présenterons les différentes briques qui composent un tel site et verrons que les outils utilisés sont libres et adaptés à un site pour l’enseignement, en particulier de l’Informatique (possibilités d’intégrer des exercices auto-corrigés de programmation). Nous donnons des exemples visuels de ce qu’autorise la solution que nous nommerons pmm (pour pyodide-mkdocs-material), accompagnés d’explications sur la mise en œuvre. Enfin, nous terminons par un exemple possible d’étapes à suivre pour aller plus loin et commencer son propre site.
MOTS-CLÉS • ressource en ligne – mkdocs – pyodide – exerciseur – informatique – NSI – Python
Figure : Site créé lors de l’atelier
Objectifs de l’atelier
Cet atelier avait pour but de présenter et initier les collègues à la mise en ligne de ressources pédagogiques, notamment pour l’enseignement de l’Informatique (mais la solution s’utilise aussi dans d’autres disciplines). Les systèmes de gestion de contenus (CMS [1] en anglais) offrent déjà la possibilité de créer des sites web dont l’édition se fait entièrement en WYSIWYG [2]. La solution présentée ici se distingue de cette approche à plus d’un titre.
D’une part l’ensemble du site est construit autour de fichiers au format texte et son contenu décrit dans un langage de balisage élémentaire (markdown). Il ne nécessite donc pas l’installation d’une base de données côté serveur. D’autre part, l’outil permet d’interpréter du code Python directement dans les pages du site, ce qui autorise, par exemple, l’intégration d’exercices auto-corrigés.
Les outils utilisés sont libres et permettent la production d’un site offrant divers avantages : conformité totale avec les règles du RGPD, adaptatif (utilisable aussi bien sur un écran large que sur un téléphone portable) et la possibilité d’une pédagogie plus active en variant les éléments au sein de la ressource : sections de texte à lire, vidéos à visionner, quiz à réaliser, exercices de programmation validés dans le navigateur.
L’objectif de cet article, en montrant des exemples et en donnant les premières étapes, est d’inciter les enseignants à mettre en ligne leurs propres ressources. Il est aussi un témoignage d’une expérimentation collective réussie : premières expérimentations par un petit groupe d’enseignantes, diffusion par forum de discussion et réalisation de tutoriels pour aider les collègues.
Description du projet : les quatre briques de la construction
En plus du langage Python, la solution pmm [3] repose sur quatre outils sur lesquels nous livrons quelques éléments d’informations : les auteurs, leurs usages originaux dans le cas d’un détournement dans l’utilisation faite et des bribes d’exemples illustrant la mise en œuvre concrète.
Markdown
Le langage markdown est un langage de balisage élémentaire utilisé dans divers contextes et aux multiples avantages (voir par exemple Pochet 2021). Il permet de rédiger le contenu des pages d’un site produit via mkdocs (voir paragraphe suivant). Ce format sert aussi dans les carnets jupyter (2015) présents dans l’outil académique Capytale. Ce langage permet une structuration minimale du texte (titres, images, liens, listes à puces et numérotées, emphases, etc.).
Voici un petit aperçu qui montre le code source et le résultat produit :
# Les structures linéaires
## La File
Ici nous allons présenter la **file**. Pour aller plus loin : [lien vers un chapitre de cours](https://fabricenativel.github.io/Terminale/sl/).
La file d’attente est une bonne représentation de la file :
Pour celles et ceux déjà familiarisés avec le langage HTML, le markdown est beaucoup plus minimaliste. Dans l’exemple présenté, les titres de niveau 1 et 2, l’emphase, l’image et le lien représentent pratiquement tous les balisages possibles, suffisants pour décrire les contenus.
Mkdocs et Mkdocs-material
Mkdocs est un générateur de site statique à base de pages rédigées au format markdown et de fichiers de configuration au format yaml. Conçu initialement pour la réalisation de documentations techniques, cet outil créé par Tom Christie en 2014 permet, associé à un thème particulier, la création de site à usage pédagogique.
Mkdocs-material est un thème pour mkdocs. Développé par Martin Donath depuis 2016, ce thème étend le langage markdown de base offrant de nouvelles possibilités : listing de code avec coloration syntaxique, formules mathématiques, onglets, boîtes colorées, etc. Nous verrons quelques exemples dans la prochaine section.
Pyodide et Mkdocs-pyodide
Pyodide est une distribution Python conçue pour s’exécuter dans un navigateur à l’aide de Node.js et basée sur WebAssembly. Mkdocs-pyodide est l’intégration de Pyodide dans mkdocs réalisée par Vincent Bouillot (2021) et qui permet de disposer, dans une page du site, d’un IDE et/ou d’une console Python.
Le rendu ci-dessous d’un IDE pré-rempli et d’une console est obtenu par la commande suivante dans le fichier source en markdown :
IDE(‘exercice.py’)
Une forge git
L’ensemble des documents est déposé sur une forge qui, par un mécanisme d’intégration continue, génère les pages HTML. La modification d’un des fichiers texte déclenche automatiquement une mise à jour. L’auteur du site ne gère ni serveur, ni base de données, ni hébergement.
Expérimentations réalisées
Une solution de mise en ligne de ressources pédagogiques, doit offrir des possibilités d’adaptation à chaque enseignant. Sans être exhaustive, voici une liste de quelques exemples :
Une navigation personnalisable
Comme déjà mentionné, un site pmm s’appuie sur un ensemble de fichiers textes, pour le contenu et la configuration. L’interface de navigation du site final fait partie des éléments configurables. Ci-dessous un menu vertical associé à une table des matières de la page courante, ainsi qu’un menu horizontal (source : fabricenativel.github.io/Premiere/donneestable/) :
Cet autre exemple montre un menu vertical à tiroirs, sans menu horizontal ni table des matières (source : https://natb_nsi.forge.aeif.fr/ressources/cours/site_cours/sites/) :
Des boîtes colorées pour structurer
Les élèves ont besoin de repères visuels pour se retrouver facilement dans un document ressource : différencier exercices, définitions, exemples, etc. Les admonitions (boîtes colorées repliables ou pas) de mkdocs-material permettent cela, sans intervention de l’auteure de la page sur la mise en forme. Par exemple, le texte suivant fourni les trois boîtes (repliables ou non) de l’image d’après :
!!! note ’Définition de File’
La **File** est une structure de données linéaire fondée sur le principe premier arrivé, premier sorti_ (_FIFO_ en anglais).
???+ example ’Un exemple de File’
Ci-dessous l’exemple d’une file...
???- exercice ’Exercice’
Dessiner la file obtenue...
Des minis quiz pour une pédagogie plus active
Ci-dessous nous avons l’exemple d’un mini-quiz à l’intérieur d’une page de cours. Ce quiz est présenté dans une de ces admonitions vues précédemment associée à deux onglets : l’un pour le quiz, l’autre pour le corrigé :
Intégration d’exercices de programmation
Le site web e-nsi.forge.aeif.fr/pratique est un exemple de co-construction de la communauté NSI : une plateforme d’entraînement à l’épreuve pratique du baccalauréat. Il s’agit d’un site en pmm intégrant des exercices auto-corrigés de programmation :
L’image suivante montre la partie basse de la page où se trouve la zone d’interaction pour l’élève : l’IDE et la console Python pour définir et tester son code et un ensemble de boutons pour les différentes actions (validation, sauvegarde, recharge, etc.).
Conclusion
Les sites pmm fondés sur les briques logicielles pyodide, mkdocs, mkdocs-material et le langage markdown ne sont pas une révolution : d’autres solutions de mises en ligne de ressources existent. Néanmoins, ils sont un exemple d’utilisation opportuniste d’outils détournés de leur usage original à des fins pédagogiques. La possibilité offerte d’y réaliser des exercices de programmation est un vrai plus par rapport à des CMS classiques. Il s’agit d’une découverte communautaire réussie. Chaque enseignant peut commencer sa propre expérimentation. Voici une liste d’étapes possibles :
Étape 1
Suivre un tutoriel pour découvrir la solution et créer un premier site, sans mkdocs-pyodide dans un premier temps. Différentes solutions sont possibles :
Étape 2
Installer et utiliser pyodide, en suivant les instructions de son auteur, Vincent Bouillot (2021).
Étape 3
Pour aller plus loin et passer de son premier site web à un site ressources pour son enseignement, il est possible de rejoindre la communauté NSI et notamment le forum dédié aux échanges et sa section dédiée aux outils de travail.
Références
Bouillot, V. (2021) Site tutoriel pour intégrer IDE Python dans un site mkdocs bouillotvincent.gitlab.io/pyodide-mkdocs/
Donath, M. (2016) Site officiel du thème mkdocs-material squidfunk.github.io/mkdocs-material/
Pochet, B. (2021). Markdown & vous. https://e-publish.uliege.be/md/
Poulain, N. (2022) Environnement Capytale, Didapro 9, atelier. capytale2.ac-paris.fr/wiki/
Forum d’enseignants de NSI possédant une rubrique dédiée mooc-forums.inria.fr/moocnsi/ (2019)
Jupyter Team (2015), jupyter.org