Éditeur markdown pour les sciences

Salut

Ça fait un petite moment (quelques années ) que je ne viens plus régulièrement sur ZesteDeSavoir, et ça commence à me manquer

Je reviens avec la présentation d’un projet que je réalise en parallèle de mes études (je redouble une PACES cette année).

J’ai crée cet éditeur pour coller à mon besoin (écrire/éditer rapidement mes cours de fac), tout simplement  ! S’il peut être utile à d’autres, tant mieux

Génèse

Au premier semestre de l’année dernière, j’ai passé beaucoup (beaucoup beaucoup) d’heures dans Libre Office à remettre en forme et à éditer des cours que j’avais d’étudiants d’années supérieures, parce que je suis incapable de les comprendre si les phrases ne sont pas parfaitement claires et la présentation consistante.

À partir de ce constat, aux vacances de noël j’ai entrepris de coder un convertisseur de fichier .odt vers markdown pour convertir les cours que j’avais d’étudiants d’années supérieures au format odt en markdown, qui me semblait plus pratique/rapide à modifier. LaTeX ne me convenait pas car trop long/complexe à rédiger, ça ne m’aurait pas fait gagner de temps.

Il me fallait mettre des formules de maths, la syntaxe des maths de libre office me plaisait bien de par sa simplicité à rédiger. Aucun éditeur markdown à ma connaissance ne permettais d’utiliser cette syntaxe. Je me suis résolu à créer un éditeur (avec prévisualisation intégrée). Étant habitué à utiliser Neovim pour écrire du code, j’ai décidé que j’allais l’utiliser comme éditeur.

Le cahier des charges étant grossièrement esquissé, je me suis lancé dans le code. Vu le peu de temps que j’avais (~10j avant le début du 2ème semestre, il fallait que ça soit opérationnel avant) j’ai fait ce que j’ai pu pour que ça marche. C’était du freestyle, c’était sale, c’était à la demi-journée près, mais ça fonctionnais à la rentrée de janvier

La base de code étant dégueu et mal organisée, j’ai amélioré tout ça pendant les vacances d’été. On rédige maintenant dans l’éditeur comme sur Zeste de savoir, avec quelques petits trucs en plus

Voici une capture d’écran de l’éditeur (il n’a rien de foufou visuellement), vous pouvez cliquer dessus pour l’agrandir :

Résumé des fonctionnalités

• Toutes les fonctions supportées par zmarkdown, comme les balises de code, les images, …
• Support des formules de maths avec la syntaxe asciiMath avec $$ et $ comme délimiteurs
• Dessin rapide de molécules avec la syntaxe SMILES avec €€ et € comme délimiteurs
• Syntaxe de tableau simple et efficace
• Neovim comme éditeur, fait gagner beaucoup de temps
• Double click sur une image pour la modifier dans Gimp
• export HTML & PDF

Testez le  !

N’hésitez pas si vous avez un soucis pour l’installer ou pour l’utiliser, je ferais de mon mieux pour essayer de vous aider

Installation

L’éditeur requière Nodejs 14, Neovim, et d’autres dépendances notamment pour faire fonctionner node-gtk

• Pour installer tout ça sur Debian/Ubuntu :

sudo apt install curl -y
curl -sL https://deb.nodesource.com/setup_14.x | sudo bash -
sudo apt-get install -y nodejs
sudo apt-get install build-essential git gobject-introspection libgirepository1.0-dev libcairo2 libcairo2-dev -y
sudo apt-get install libwebkit2gtk-4.0 -y
sudo npm install -g markdown-math-editor

• sur d’autres platformes

  jetez notamment un oeil à node-gtk install

  Pour le moment, cela peut ne pas bien fonctionner sur d’autres platformes que Debian/linux, notamment à cause des dépendances. C’est au programme de se séparer des dépendances les plus restrictives.

Usage

Exécutez simplement :

markdown-math-editor file.md

Vous pouvez configurer votre gestionnaire de bureau pour ouvrir tous les fichier .md avec cet éditeur

Je vous conseille également de tester le convertisseur de fichier .odt vers markdown , il est complémentaire à l’utilisation de l’éditeur si comme moi vos sources sont des odt (ou des fichiers word que vous convertissez en odt avec libreoffice)

Côté technique

Pour le côté technique, vu le peu de temps que j’avais (~10j avant le début du 2ème semestre, il fallait que ça soit opérationnel avant) j’ai fait avec ce que je connaissais : Node.js.

J’ai utilisé node-gtk (avec son lot de bugs obscurs ralentissant/complexifiant le développement) pour créer une fenêtre qui intègre un terminal virtuel (à gauche) pour Neovim et un moteur de rendu (WebKitGTK, à droite) pour le rendu. Ce n’était pas prévu au départ, mais ça devient un genre d'electron-like .

Pour la conversion markdown -> html je vais bidouiller (salement) et utiliser remarkJS/UnifiedJS dont j’avais entendu parler. J’utiliserais notamment remark-grid-table issus de zmarkdown le convertisseur utilisé par Zeste de savoir  !

Le code était dégueu, au début de l’été j’ai tout repris.

J’ai finis par intégrer zmarkdown et le customiser pour remplacer la syntaxe de math de LateX, par la syntaxe AsciiMath. Ça m’as permis de pas mal nettoyer le code de l’éditeur  ! J’y ai ajouté quelques customisations :

• la possibilité de dessiner rapidement des molécules avec la syntaxe SMILES avec €€ et € comme délimiteurs

• Une syntaxe supplémentaire de tableau que je trouve plus simple et plus efficace la plupart du temps

• la possibilité de définir la largeur des images (en % ou en px) en ajoutant =50% après l’url de l’image :

  ![alt](img.png) => ![alt](img.png =40%)

On rédige donc dans l’éditeur comme sur Zeste de savoir, avec quelques petits trucs en plus

Voici un shéma qui explique le fonctionnement actuel du programme :

Vous pouvez trouver le code source ici

Future du projet

L’éditeur va évidemment continuer à évoluer, en fonction de mes besoins notamment, comme je l’utilise une bonne dizaine d’heures par jour

Pour le moment, j’aimerais :

• Permettre l’utilisation d’autres éditeurs que Neovim, qui peut être déroutant pour les ceux qui ne l’ont jamais utilisé

• Réaliser le rendu dans un terminal avec BlessedJS, ce qui permettra :

  • de faire tourner l’éditeur dans un terminal
  • Virer WebKit des dépendances, pour alléger la consommation de ressources
  • Virer GTK des dépendances

  C’est un gros bout que je réaliserais probablement à l’été 2021

• Ajouter des tests unitaires à toutes les parties du code

• ☑ Cloisonner la partie qui réalise la conversion du markdown en html dans un package différent de l’éditeur en lui même, pour faciliter sa réutilisation

• Optimiser plus le rendu (réduire le nombre de calculs à faire pour convertir le markdown en html, notamment pour économiser la batterie)

• Afficher une table des matières générée automatiquement à partir des titres

• Permettre d’ouvrir directement les fichier odt (= les convertir en markdown à l’ouverture grâce au convertisseur odt vers markdown)

  J’ai présenté brièvement le convertisseur convertisseur de fichier .odt vers markdown , il est également amené à évoluer aussi

Des questions ? Un petit commentaire ? Des idées ? N’hésitez pas, je sors du repas donc je ne mords pas  !

Sympathique comme projet !

J’ai utilisé node-gtk (avec son lot de bugs obscurs ralentissant/complexifiant le développement)

Pourquoi n’as tu pas utilisé GJS, qui permet d’utiliser GTK/GObject en javascript, et qui est développé au sein du projet GNOME ? L’avantage est que ça existe depuis longtemps, que tu peux trouver d’autres applications l’utilisant pour t’en inspirer/t’aider, et que tu peux toujours demander de l’aide si besoin sur le forum GNOME. En sois, tu connais Node.JS, mais surtout JavaScript. Est-ce qu’utiliser node-gtk t’as vraiment aidé plus qu’en utilisant du JS vanilla ?

Virer GTK des dépendances (je n’ai pas encore d’idée de comment)

Pourquoi faire ?

Pourquoi n’as tu pas utilisé un éditeur markdown existant, quitte à le modifier pour intégrer tes améliorations (il me semble notamment que ta syntaxe pour la tableau est déjà plus ou moins celle du GFM (Github Flavored Markdown), qui est pris en charge par beaucoup d’éditeurs markdown) ?

Merci  !

Je ne crois pas avoir fait de comparatif node-gtk vs GJS

Honnêtement c’était tellement le rush à cette période, j’étais tellement fatigué (7 jours de repos week-ends compris sur 13 mois…), j’ai juste cherché à faire un truc fonctionnel, j’ai pris la première lib que j’ai trouvé en cherchant node make window et j’ai sauté dans le code.

node-gtk me sert uniquement à avoir neovim et webkit dans une seule et même fenêtre, je ne peux pas faire ça avec du JS vanilla

J’ai mal formulé, c’est peut être de node-gtk dont je veux me séparer plutôt que de GTK, pour que l’éditeur soit plus multiplateforme. Faut que je cherche des solutions, GJS en est peut-être une

Je n’ai pas utilisé un éditeur markdown existant parce que vu le temps que j’avais pour coder ça, je pensais avoir un résultat me convenant en assemblant (comme j’ai pu) des briques toutes faites, alors que j’étais loin d’en être sûr qu’en partant dans un fork j’aurais un truc potable dans le temps imparti, vu le nombre de modifs que je voulais faire

Si j’arrive à faire un rendu en console (le plus problématique étant les images), je pourrais virer à la fois WebKitGtk et Gtk, c’est la solution que je voudrais privilégier

Sauf que techniquement ça semble compliqué d’afficher des images en console (en même temps, ce n’est pas fait pour ) : si j’ai bien compris, le framebuffer permettrais de faire ça, mais ça n’est accessible qu’en TTY et est obsolète. De plus je n’ai jamais réussi à l’utiliser…

J’avais oublié l’existence de Libcaca, et par là même l’existence de BlessedJS qui est une lib permettant (entre beaucoup d’autres) d’afficher des images dans le terminal alors que je l’utilisais il y a quelques années

Un grand merci @Vanadiae  !

J’ai trouvé comment je vais m’occuper l’été prochain, parce que je n’aurais pas le temps de développer un truc aussi gros avant

Le résultat est très sympa pour de la prise de notes !

Tu n’as pas peur que ce soit difficilement maintenable ?

C’est vrai que LaTeX a un ticket d’entrée très très cher, mais il est peut-être aussi plus low-tech ce qui permet de voir à long terme plus facilement

Beau travail même si le code doit être mis au propre, quand le temps presse, la priorité est sur le fonctionnement .

Ça me rappelle quand j’étais en master et que j’avais cours de théorie des graphes… À la vue de tous les symboles sur le tableau, j’ai vite abandonné Libre Office pour le papier/stylo et je transformais la photo du cours en scan avec un script python.

Bon courage pour les prochaines étapes de dev

Merci @Holosmos  !

Maintenant que j’ai refait/ré-organisé et le code, et surtout depuis que je ré-utilise zmarkdown, il y a beaucoup moins de code, et donc beaucoup moins de maintenance à faire

Comme j’ai fractionné le code, je n’ai quasiment plus que des petits packages à maintenir, avec chacun une tâche bien définie :

• https://github.com/Drulac/odt2md
• https://github.com/Drulac/remark-change-image-paths
• https://github.com/Drulac/rehype-smiles
• https://github.com/Drulac/remark-smiles
• https://github.com/Drulac/rehype-lo-math
• https://github.com/Drulac/surcouche-remark-grid-table

C’est infiniment plus facile à maintenir qu’un gros tas de spaghettis obscures

Je trouve LaTeX très très verbeux, et ça me semble contradictoire avec le fait de simplifier/rendre rapide la prise de note et la modification de cours

Merci @thibsc  !

Au S2 j’arrivais à recopier les diapos des profs en live y compris les formules, grâce à l’éditeur ! C’est mes potes qui étaient contents

@Drulac, tu m’étonnes qu’ils devaient être content. On avait fini par trouver la solution d’un google doc ou une partie écrivait le texte, les autres mettaient en forme, d’autres faisaient le rendu des formules, ça fonctionnait bien en coopération et à la fin du cours, toute la classe avait le cours fini et bien présenté

Au début aussi je trouvais LaTeX peu efficace. Mais en réalité avec l’expérience et une fois que mes classes sont prêtes (ce qui a demandé un bon millier de lignes de code) c’est très très souple.

D’ailleurs LuaLaTeX permet de « scripter » beaucoup de comportements. J’ai vu passer un package de graphe qui produit un graphe automatiquement à partir de la description des arêtes par exemple

Tu as jeté un coup d’œil du côté de Typora, cela fait des années que je l’utilise pour prendre mes notes de cours en MD.

Je m’en sers aussi pour rédiger des rapports, que je convertis après en LaTeX avec zmarkdown (qui n’est pas intégré, je me suis fait un script qui me génère un zreport (dérivé du template des tuto de ZdS)).

En revanche ce qui risque d’être embêtant pour toi, c’est qu’il ne gère pas (pour le moment en tout cas) la syntaxe SMILES.

Je m’en sers aussi pour rédiger des rapports, que je convertis après en LaTeX avec zmarkdown

Tu peux aussi importer du MD dans (lua)latex normalement, pas besoin de convertir

edit : ok je pensais que tu faisais du MD sans les ajouts de zmd

En effet, mais il ne gère pas les syntax custom de zmarkdown (comme les bloc de question, etc.)

Typora ne me satisfait pas parce que je préfère un markdown et un rendu bien séparés

A c’est intéressant, c’est typiquement le truc que je déteste

Chacun ses goûts

C’est une des raisons pour lesquelles j’ai quitté LibreOffice : mélanger fond/forme et rendu, c’est pas mon truc

Salut,

Mon message n’est que mon avis, mais je pense qu’il peut être intéressant soit pour toi, soit pour une personne voulant écrire un outil similaire. En tout cas, ça n’enlève rien au fait que tu as fait un beau projet !

C’est un peu amusant ce que tu dis sur la séparation markdown/rendu, parce que je me disais justement que ce qui me "gêne" avec ton projet (et qui est d’ailleurs responsable de sa complexité), c’est qu’ils ne sont pas assez découplés.

Je n’écris pas en Markdown mais plutôt en LaTeX, mais l’idée est la même. Mon workflow est le suivant, j’écris mon LaTeX dans Vim, et j’ai latexmk qui tourne en permanence en fond et recompile mon projet LaTeX dès qu’une source est modifiée (i.e. je change une image ou j’enregistre une des sources). J’ai un lecteur PDF qui m’affiche le fichier et le recharge automatiquement lorsqu’il change. Tout les éléments sont donc parfaitement découplés les uns des autres, et donc interchangeables par ce que l’on veut (typiquement, si dans un instant de folie je voulais éditer le fichier tex avec gedit, je peux et ça change strictement rien au reste puisqu’il y a zéro couplage entre les éléments). Les trois éléments (éditeur, moteur de rendu, affichage) sont trois programmes complètement indépendants, et le couplage se fait via le système de fichier.

Je me dis qu’ici, ce qui te coûte cher et force beaucoup de couplage, c’est de vouloir faire du rendu instantané (et donc coupler rédaction et forme). Là où je suis très dubitatif, c’est sur l’utilité de la chose. Avoir un rendu est utile pour vérifier par exemple qu’une formule a bien la tronche qu’on souhaite ou qu’un tableau est bien formé tel que voulu. Or, un rendu instantané n’apporte rien là-dessus par rapport à un rendu à l’enregistrement du Markdown puisqu’il sera incapable de rendre quoique ce soit d’intéressant tant qu’on est en train de les écrire (puisque typiquement, quand on en train d’écrire une formule ou un tableau, ils sont généralement mal formés). Là où le rendu instantanée peut donner un rendu potable, c’est sur les éléments de markup mineurs comme les titres, les emphases, les listes. Mais là, l’intérêt est réduit par le fait que le markdown est déjà plutôt lisible (une liste ressemble à une liste) et n’importe quel éditeur décent va mettre en italique et en gras les emphases, et faire ressortir les titres. De fait, j’ai l’impression qu’en se débarrassant de la contrainte "rendu instantané", tu perds peu voire rien en UX, mais tu gagnes beaucoup en flexibilité sur le code et sur le fait de laisser à l’utilisateur un choix très large sur les outils à utiliser (et ça, c’est un gain énorme en coût de développement et en UX).

La partie vraiment centrale du projet, c’est le moteur de rendu de ton Markdown avancé. Si tu arrives à avoir un éditeur et un visionneur quelconque autour de ce moteur (soit en réduisant considérablement le couplage, soit en l’enlevant complètement), le projet devient extrêmement intéressant. Il est assez simple d’enlever le couple éditeur/moteur (il suffit que le moteur surveille les fichiers, soit avec la date de modification, soit avec un hash pour quelque chose de plus propre). Le couple moteur/affichage est sûrement un peu plus délicat si tu ne produis pas un format affichable typiquement par un navigateur web (je suis pas sûr de comprendre quel est le format de sortie [EDIT : c’est de l’html, donc ça devrait pas être trop compliqué]).

Merci pour ton avis et tes encouragements  !

Je serais totalement d’accord avec toi, un rendu en temps réel n’est pas forcément nécessaire pour écrire du markdown. À la base j’avais d’ailleurs configuré Neovim pour qu’il envoi les changements uniquement quand je sort de l'insert-mode.

Sauf qu’en fait je m’en sers peu pour écrire du markdown. 95% du temps je m’en sers pour lire des cours d’années sup, convertis en markdown avec odt2md :

• Je lis le rendu jusqu’à trouver une modif à faire (très très fréquent)
• Je fais la modif
• Je me remet à lire

Du coup, après chaque modif, il y a besoin d’un rendu. Autant ne pas avoir effectuer une commande/enregistrer. Du coup j’ai modifié la config pour faire un rendu à chaque caractère modifié (avec un throttle de 1 rendu/s max, pour pas bouffer toute la batterie pendant que je retape un cours)

Sachant qu’au rythme de 200 modifs par heures, 10–12h/j, on tape les 2000–2400 modifs par jours. Ça prendrais un petit temps en cumulé, et je suis pas sûr que le disque apprécie à long terme

Pour la séparation entre l’éditeur et le moteur de rendu, c’est plutôt bien séparé en fait

node-gtk affiche un terminal virtuel (dans la moitié gauche de l’éditeur). Je lance neovim dans ce terminal virtuel, avec en argument une commande à exécuter en cas de modifs.

Comme on peut le voir sur le shéma, en cas de modifs neovim exécute simplement le fichier neovim-hook-handler.js, qui via TCP transmet les modifs à md2html/engine.js (le script qui coordonne éditeur, moteur de rendu et affichage)

Si je met une option (c’est prévu) pour utiliser d’autres éditeur, rien ne m’empêche de définir que le comportement par défaut avec tous les éditeurs c’est de surveiller les fichiers, et que pour neovim/vim exceptionnellement fonctionner comme il fonctionne actuellement

Le code est assez souple et cloisonné pour permettre de fonctionner des deux manières

La sortie est en HTML, l’affichage se fait actuellement dans WebKitGtk (intégré à la fenêtre), mais avec assez peu de modifs il pourrait se faire dans n’importe quel navigateur en temps réel (après le CSS est fait pour WebKit, le rendu n’est pas exactement le même dans firefox par exemple )

L’été prochain je coderais l’affichage (séparé du moteur de rendu) dans un terminal avec blessedJS

Je ne sais pas ce que ça donne avec ton genre de contenu, mais il faut voir aussi que dès que la source est un peu longue, l’affichage ne peut pas se faire suffisamment vite. Et ce n’est pas forcément grave, compiler un programme qu’on code peut prendre du temps … pas de raison que ça soit autrement pour du texte.

Mais je pense qu’on commence à aller à l’encontre de l’esprit MD-HTML. Car typiquement ce sont des outils qui ne font pas, ou très peu, de travail typographique (pas d’empagement, pas de justification, etc.) et donc que l’intérêt du rendu est beaucoup plus bas que ce qu’on pourrait avoir avec du LaTeX.