Journal générer des cours en Markdown avec Mkdocs-et

Posté par  . Licence CC By‑SA.
Étiquettes :
24
29
mar.
2021

Bonjour,

j'ai fait un petit outil pour générer sur une page web des cours écrits en Markdown :

Mkdocs-et

C'est basé sur le générateur de sites statique Mkdocs et le thème Material for Mkdocs, et c'est en fait un gros script bash 1 qui apporte quelques possibilités dont j'avais besoin :

  • faire apparaître progressivement les planches de cours, TD et TP (Mkdocs publie tout d'un coup) ;
  • s'installer tout seul dans un virtualenv avec les packages qui vont bien ;
  • avoir un truc déjà tout configuré sans avoir à relire toute la doc ;
  • publier le site avec un rsync,

et d'autres bricoles (par exemple embarquer un bout de PHP pour publier des notes, voir l'exemple).

Pour tester le script je me suis amusé à faire toute une doc, et quelques "cours" (Lectures) et "TP" (Practical Work) sur Markdown que l'on peut filtrer, c'est-à-dire publier partiellement (du cours 1 au cours x, du TP 1 au TP y).

Tout le site est généré avec le script, et les sources sont dans le tarball téléchargeable.

Bonne lecture… 2


  1. Je viens de finir un gros cours d'administration Unix alors j'étais chaud ! 

  2. Des typos ou mauvaises tournures ont pu m'échapper, je vous remercie de me les signaler. 

  • # J'aime beaucoup Markdown

    Posté par  . Évalué à 3 (+1/-0). Dernière modification le 29/03/21 à 13:57.

    Markdown et moi c'est un peu l'amour.

    Ce langage a réussi sur un point où html et latex (avec leurs écosystèmes) ont échoué : permettre à quelqu'un de non-technique de séparer forme et contenu d'un document.

    Bien évidemment, c'est beaucoup plus limité, mais n’empêche que j'adore.

    • [^] # Re: J'aime beaucoup Markdown

      Posté par  . Évalué à 1 (+0/-0).

      Cela vaut aussi pour des profils plus techniques : j'aime bien LaTeX, mais pour rédiger mes cours, je ne saurais me passer de Markdown et Pandoc.

      Ajoute à ça un éditeur distraction-free comme Apostrophe, c'est vraiment le pied.

    • [^] # Re: J'aime beaucoup Markdown

      Posté par  . Évalué à 3 (+1/-0).

      Bof, markdown, ca a quand même bien trop de lacunes.
      Par exemple, ca gère très mal les tableaux ou pas du tout les includes

      Dans le genre, https://asciidoc.org/ est bien plus avancé.

      • [^] # y a mieux

        Posté par  . Évalué à 2 (+1/-0).

        ASCIIDoc est sur le même terrain que rST : ils se posent comme des alternative à (Con|La|Plain|Xe)Tex et DocBook SGML/XML pour de la documentation technique et conséquente (types longs articles ou livres) destinés à l'écrit (PS/PDF/ePub/papier/…) On est loin de la prétention de Markdown.

        Markdown, de base ne gère pas du tout les tableaux. Ça fait partir des diverses choses rajoutées par les divers dialectes avec leurs incompatibilités (ce n'est pas sans rappeler la glorieuse époque des foisonnants basic/lisp/logo.) À côté, je préfère quand même textile ou wikicreole (même si j'utilise plus le format dokuwiki) qui permettent vachement plus que le markdown et offrent une certaine pérennité (on ne se retrouve pas enfermé dans une implémentation) pour mes notes. (Quand j'ai besoin de plus de possibilités ou plus de contrôles et d'expressivité, je fais du restructuredtext ou du LaTeX)

      • [^] # Re: J'aime beaucoup Markdown

        Posté par  . Évalué à 2 (+1/-0). Dernière modification le 30/03/21 à 08:40.

        Avec l'outil présenté il y a l'embarras du choix :

        • l'include Markdown --%<-- "file" lien
        • l'include Jinja2 {% include "file" %} lien
        • l'include javascript <script src="file"></script> lien
        • l'include PHP <?php include "file" ; ?> lien

        Pour ce qui est des tableaux, il y a une extension (que je n'ai pas essayée), et on peut aussi mettre des tableaux html.

        Le but est de faire des pages un peu jolies sans y passer des heures (contrairement à LaTeX, que j'aime beaucoup, mais faire des slides bien présentés en LaTeX est hyper-chronophage).

  • # Pour les notes des étudiants... Aussi du markdown !

    Posté par  . Évalué à 4 (+3/-0).

    Salut, pour compléter l'outil et permettre aux étudiants d'être efficaces, voici un tutoriel pour prise de cours avec des logiciels libres basé sur markdown (pandoc / ghostwriter).

    Pour vous donner une idée, ça peut donner ça : Cours médecine

  • # Très chouette outil

    Posté par  . Évalué à 2 (+1/-0).

    Merci !

  • # Premier retour : dossier bin et tmp

    Posté par  . Évalué à 2 (+1/-0). Dernière modification le 31/03/21 à 10:24.

    Super script, c'est l'outil qui me manquait pour mes docs markdown.

    Par contre je trouve les choix de dossier discutables pour bin et tmp :

        # Temp dir for mkdocs; must be on same partition then .md sources because
        # mkdocs changes detection needs hard links.
        TMP_DIR="$HOME/tmp/mkdocs-et-$$"
    
        # Directory for the virtualenv
        VENV_DIR="$HOME/bin/venv-mkdocs-et"

    Je suis bordélique de nature et j'essaie de minimiser au maximum les dossier des applications et là le dossier bin qui s'installe tranquille à la racine de mon home ça me fait dresser les cheveux sur la tête.

    Pareil pour le tmp, c'est le dossier que j'utilise pour faire des tests et que je shoote/vide régulièrement donc mauvaise pioche.

    Après l'avantage c'est que c'est un script donc je vais de ce pas changer ça :) et merci encore pour avoir partagé ton travail.

    • [^] # Re: Premier retour : dossier bin et tmp

      Posté par  . Évalué à 1 (+0/-0). Dernière modification le 31/03/21 à 10:00.

      Zut, j'ai raté le formatage du commentaire et je n'arrive plus à le modifier, quelqu'un peut corriger?

    • [^] # Re: Premier retour : dossier bin et tmp

      Posté par  . Évalué à 2 (+1/-0).

      Merci pour le compliment !

      Oui ce choix des dossiers est un peu personnel mais comme dit c'est configurable. J'aurais pu les mettre en répertoires cachés. Comme j'ai déjà un ~/bin avec tous mes scripts et un ~/tmp avec des trucs à jeter mais qui doivent quand même survivre à un reboot, ça allait bien.

      Le répertoire temporaire est détruit à la sortie du script ; comme il y a un $$ dans le chemin, ça permet de lancer en même temps mkdocs-et.sh serve -all dans un terminal, et de faire dans un autre terminal de temps en temps un mkdocs-et.sh publish -all sans interrompre le premier, comme ça ils ont chacun leur propre tmp et ne se marchent pas sur les pieds.

      L'important est que tout soit dans la même partition pour les hard links (donc pour moi ça exclut /tmp car /home a sa propre partition).

      • [^] # Re: Premier retour : dossier bin et tmp

        Posté par  . Évalué à 1 (+0/-0).

        Ok je comprends mieux pour le tmp, de mon côté j'ai tout déplacé dans le dossier de l'application, de cette manière ça ressemble à l'arborescence de mes applis qu'elle soient professionnelles ou personnelles (c'est le côté professionnel qui a déteint en fait).

      • [^] # Re: Premier retour : dossier bin et tmp

        Posté par  . Évalué à 3 (+1/-0).

        XDG Base Directory est une bonne spécification pour ça : https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html

        Tu as entre autre un dossier de cache et un dossier de runtime.

        • [^] # Re: Premier retour : dossier bin et tmp

          Posté par  . Évalué à 1 (+0/-0).

          Il y a 2 inconvénients :

          • je ne suis pas certain que ces répertoires soient standards sur MacOS ;
          • on ne pense jamais à aller voir dans .local et .cache ce qui s'y trouve, noyés qu'ils sont dans la masse des répertoires cachés…
          • [^] # Re: Premier retour : dossier bin et tmp

            Posté par  . Évalué à 1 (+0/-1).

            je ne suis pas certain que ces répertoires soient standards sur MacOS ;

            Quitte à ne pas être standard autant appliquer le standard XDG (s'il n'y a pas d'alternative sur MacOS). XDG défini leur valeur par défaut s'ils n'existent pas.

            on ne pense jamais à aller voir dans .local et .cache ce qui s'y trouve, noyés qu'ils sont dans la masse des répertoires cachés…

            Ce n'est en multipliant les dossiers pour chaque idée des développeurs que ça va s'arranger.

            Il est très utile de respecter ces dossiers par exemple quand on cherche à sauvegarder sur dossier personnel par exemple (ce n'est pas que de l'esthétisme).

Envoyer un commentaire

Suivre le flux des commentaires

Note : les commentaires appartiennent à ceux qui les ont postés. Nous n’en sommes pas responsables.