Aller au contenu

Mise à disposition du site à la fin du cours

Lorsque le cours est terminé, il serait bon de distribuer une version “offline” du site aux étudiants. En effet, le site va probablement évoluer au cours des années à venir et c’est intéressant de conserver la version correspondante à l’année d’étude.

Une solution serait de convertir le site en PDF et il existe plusieurs “plugins” qui permettent de le faire, mais cette solution souffre de plusieurs inconvénients:

  • La mise en page est souvent hasardeuse et les sauts de page ne tombent pas toujours où l’on voudrait
  • Les vidéos et autres animations ne sont pas possibles dans un PDF
  • Les documents (PDF) intégrés au site ne sont également plus disponibles

Une autre solution, et c’est celle que nous conseillons, consiste à produire un fichier zip avec le contenu du site. Pour cela, nous allons encore modifier le script serve pour qu’il permette aussi la génération du site (build) :

.devcontainer/scripts/serve
#!/usr/bin/env bash

set -o errexit
set -o pipefail
set -o nounset

export SELECT_WEEK="999"
export SHOW_SOLUTION="999"

mode="serve"
while getopts "bw:s:" opt; do
    case ${opt} in
    b)
        mode="build"
        ;;
    w)
        SELECT_WEEK=$OPTARG
        ;;
    s)
        SHOW_SOLUTION=$OPTARG
        ;;
    \?)
        echo "Usage: serve [-b] [-w week] [-s solution]" 1>&2
        exit 1
        ;;
    :)
        echo "Invalid option: $OPTARG requires an argument" 1>&2
        exit 2
        ;;
    esac
done

if [ $mode = "build" ]; then
    # Build MkDocs
    mkdocs build -f config/mkdocs.yml
else
    # Serve MkDocs
    mkdocs serve -f config/mkdocs.yml
fi

Régénérez le devcontainer avec Ctrl+Shift+P ou Cmd+Shift+P et cherchez Remote-Containers: Rebuild Container.

La commande serve -b crée maintenant un dossier public contenant la totalité du site.

Dans ce dossier, ajoutez encore un fichier .prefix indiquant le préfixe du site. Vous trouverez ce préfixe dans le fichier config/mkdocs.yml à la ligne commençant par site_url. Pour rappel, voici le début du fichier config/mkdocs.yml de notre exemple :

config/mkdocs.yml
site_name: My Education Site
site_url: https://heia-fr.github.io/mkdocs-edu-howto/
...

Le préfixe c’est la partie de l’URL qui suit le nom du serveur. Dans notre exemple, le nom du serveur c’est heia-fr.github.io et le préfixe est donc /mkdocs-edu-howto/

Nous générons donc le fichier .prefix avec la commande suivante:

echo "/mkdocs-edu-howto/" > ./public/.prefix

Nous pouvons maintenant compresser le dossier public avec la commande zip :

cd public && zip -FS -r ../my-website.wzip . && cd ..

Vous pouvez maintenant distribuer le fichier my-website.wzip à vos étudiants.

Ce fichier .wzip peut être utilisé avec programme zipserve qui permet de servir l’archive sans la décompresser.