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

Posté par gato le 29 mars 2021 à 09:39. Licence CC By‑SA.

Étiquettes :

mar.

2021

Bonjour,

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

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 ¹ 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… ²

Je viens de finir un gros cours d'administration Unix alors j'étais chaud ! ↩
Des typos ou mauvaises tournures ont pu m'échapper, je vous remercie de me les signaler. ↩

# J'aime beaucoup Markdown

Posté par Vlobulle le 29 mars 2021 à 13:56. Évalué à 3. Dernière modification le 29 mars 2021 à 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 Letho le 29 mars 2021 à 20:20. Évalué à 1.
  
  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 ckiller le 29 mars 2021 à 22:46. Évalué à 3.
  
  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 Gil Cot ✔ (site web personnel, Mastodon) le 30 mars 2021 à 05:48. Évalué à 2.
    
    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)
    
    “It is seldom that liberty of any kind is lost all at once.” ― David Hume
    - [^] # Re: y a mieux
      
      Posté par barmic 🦦 le 30 mars 2021 à 08:34. Évalué à 2.
      
      Faudrait que je me penche sérieusement sur asciidoc(tor). Actuellement quand j'ai besoin de contrôle j'utilise html directement. C'est un peu verbeux, mais pas si compliqué surtout quand tu as un éditeur bien configuré (je n'ai pas pris le temps de bosser emmet pour aller plus vite).
      
      https://linuxfr.org/users/barmic/journaux/y-en-a-marre-de-ce-gros-troll
    - [^] # Re: y a mieux
      
      Posté par Gil Cot ✔ (site web personnel, Mastodon) le 03 avril 2021 à 13:30. Évalué à 1.
      
      Ah tiens, un 'nal en avait parlé : DocBook ou l'art d'écrire de la documentation
      
      “It is seldom that liberty of any kind is lost all at once.” ― David Hume
  - [^] # Re: J'aime beaucoup Markdown
    
    Posté par gato le 30 mars 2021 à 08:37. Évalué à 2. Dernière modification le 30 mars 2021 à 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 al-info le 29 mars 2021 à 18:16. Évalué à 4.

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
- [^] # Re: Pour les notes des étudiants... Aussi du markdown !
  
  Posté par barmic 🦦 le 30 mars 2021 à 08:38. Évalué à 2.
  
  Étudiant je prenais mes cours en avec txt2tags, c'est pratique de pouvoir définir ses propres raccourcis, ça se rapproche de ce que tu fais en prise de note papier/stylo.
  
  https://linuxfr.org/users/barmic/journaux/y-en-a-marre-de-ce-gros-troll
# Très chouette outil

Posté par bepolymathe le 29 mars 2021 à 22:17. Évalué à 2.

Merci !
# Premier retour : dossier bin et tmp

Posté par savitzkaia le 31 mars 2021 à 09:51. Évalué à 2. Dernière modification le 31 mars 2021 à 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 savitzkaia le 31 mars 2021 à 09:58. Évalué à 1. Dernière modification le 31 mars 2021 à 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 Benoît Sibaud (site web personnel) le 31 mars 2021 à 10:24. Évalué à 3.
    
    Corrigé, merci.
- [^] # Re: Premier retour : dossier bin et tmp
  
  Posté par gato le 31 mars 2021 à 19:03. Évalué à 2.
  
  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 savitzkaia le 01 avril 2021 à 18:36. Évalué à 1.
    
    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 barmic 🦦 le 02 avril 2021 à 14:26. Évalué à 3.
    
    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.
    
    https://linuxfr.org/users/barmic/journaux/y-en-a-marre-de-ce-gros-troll
    - [^] # Re: Premier retour : dossier bin et tmp
      
      Posté par gato le 06 avril 2021 à 10:44. Évalué à 1.
      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 barmic 🦦 le 06 avril 2021 à 11:59. Évalué à 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).
        
        https://linuxfr.org/users/barmic/journaux/y-en-a-marre-de-ce-gros-troll
# Mkdocs 1.2

Posté par gato le 18 avril 2021 à 19:13. Évalué à 1.

Mkdocs-et est passé à la version 1.2 avec des petites améliorations internes (dont les fameux chemins par défaut, qui sont maintenant dans ~/.local/share/ et ~/.cache).

J'en ai profité pour poster 2 améliorations sur le github de Material for Mkdocs ; l'auteur en a accepté l'une des 2 et refusé obstinément l'autre…

Sinon, j'ai commencé à réécrire mon cours avec, cf par exemple le CM 2 , ça donne pas mal, et aussi, le markdown reste bien lisible.

La fonctionnalité la plus importante est la boîte de recherche dans tous les documents, ça c'est cool (à la fin il y aura 20 CM et 20 TP).

Au niveau markdown il manque encore un équivalent de {tabbing} en LateX, je vais voir pour écrire un plugin à l'occasion.

Suivre le flux des commentaires

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