Pourquoi l’éditeur fonctionne comme il le fait. Pour utiliser une fonction, voir le Guide d’utilisation ; pour une tâche, les Guides pratiques.

Comment l’éditeur se comporte, et pourquoi

Chaque page de ce guide décrit une partie de l’éditeur. Quelques règles les traversent toutes, et les connaître rend la plupart de ses choix prévisibles.

Vos fichiers font foi

Le tableau des tâches, c’est todo.md ; un tableau blanc, c’est son fichier .canvas ; vos réglages, un fichier texte commenté. Il n’existe aucune copie cachée dans une base de données avec laquelle l’éditeur pourrait se désynchroniser : le tableau lit le fichier, une carte déplacée est une ligne déplacée dans ce fichier, et une modification faite à la main — ou par Obsidian, ou par git — est ce que le tableau affiche ensuite. Le prix à payer : une fonction n’est jamais plus riche que ce que son fichier peut exprimer — une carte de tableau blanc n’a qu’une couleur parce que JSON Canvas n’en prévoit qu’une. Le gain : chacune de vos notes, tâches et tableaux s’ouvre dans un autre programme, aujourd’hui comme dans dix ans.

Rien ne quitte votre machine

L’éditeur ne fait aucune requête réseau de lui-même : les aperçus ne téléchargent pas d’images sur internet, une carte de lien affiche son adresse plutôt qu’un aperçu de la page, les exports contiennent leurs images. Ce qu’il retient de vous — fichiers ouverts, dossiers récents, historique local, couleurs utilisées — est rangé dans votre propre dossier de données, jamais dans le projet : rien de ce qu’il garde n’apparaît dans git status ni dans le clone de quelqu’un d’autre. Les rares échanges avec l’extérieur sont lancés par vous : git qui récupère et pousse, et une page exportée pour être dessinée par le navigateur de son lecteur.

Rien n’échoue en silence

Une police non installée, une feuille de style introuvable, un correcteur orthographique absent, un fichier impossible à écrire : chaque cas est signalé dans la barre d’état, et l’éditeur continue avec ce qu’il a. Un réglage qui se rabat en silence, c’est un après-midi passé à douter de soi : se rabattre est toujours permis, le cacher jamais. C’est la même règle qui fait qu’un fichier de réglages défectueux ouvre l’éditeur avec les valeurs par défaut au lieu de l’empêcher de démarrer.

La rapidité se mesure

Chaque opération qui doit paraître instantanée a un budget écrit — 16 ms pour tout ce qui se fait dans une image, 4 ms pour le travail d’une frappe —, mesuré sur un portable de 2017 à chaque modification, et un budget dépassé fait échouer la compilation. C’est pourquoi certaines fonctions ont des limites qui peuvent sembler arbitraires : un tableau blanc n’affiche pas le texte des cartes trop petites pour être lues, une recherche s’arrête à mille fichiers, l’aperçu complet est un programme à part qui ne coûte rien tant qu’il n’est pas ouvert. Chaque limite se trouve là où une mesure a montré que l’expérience se dégraderait sinon.

Les réglages s’expliquent d’eux-mêmes

Chaque option est écrite dans votre fichier de réglages avec ce qu’elle fait, dans votre langue, et les valeurs par défaut sont elles aussi dans un fichier. Un réglage est une ligne que l’on peut lire, pas une case cachée au fond de trois boîtes de dialogue ; un projet peut en modifier n’importe lequel dans son propre .kaivalya/settings.toml, en n’écrivant que ce qui change.

Deux langues, à égalité

L’interface, le fichier de réglages et cette documentation existent en français et en anglais, chacun rédigé dans sa langue plutôt que traduit mot à mot, et une fonction n’est pas terminée tant que les deux ne la décrivent pas.

Aperçus et exports : qui affiche quoi

Un document markdown peut être affiché à quatre endroits, par deux moteurs de rendu différents. Ces différences ont leurs raisons ; une fois celles-ci comprises, savoir lequel regarder ne pose plus de question.

Les deux moteurs de rendu

L’aperçu en direct — à côté du texte (Ctrl+Maj+B) ou à sa place (Ctrl+Maj+V) — est dessiné dans l’éditeur lui-même, par la même boîte à outils graphique que ses menus et son texte. C’est ce qui lui permet de se redessiner après chaque frappe sans rien coûter, et de suivre le curseur titre par titre. En contrepartie, ce n’est pas un navigateur : il utilise le thème de l’éditeur, ignore votre feuille de style, et affiche tel que vous l’avez tapé ce qu’il ne sait pas interpréter — une $formule$, le [!TIP] d’un encadré, un bloc mermaid.

L’aperçu complet (Ctrl+Maj+P) et l’export sont dessinés par un moteur HTML — Blitz, avec Stylo, le système de styles de Firefox, pour le CSS — que l’éditeur lance comme un programme séparé. C’est ce qui donne à votre CSS exactement l’effet voulu, et ce qui permet de dessiner les formules et les diagrammes sous forme d’images. Le prix à payer est la mémoire : environ 117 Mo tant que la fenêtre est ouverte, rien quand elle est fermée. C’est pourquoi il s’agit d’une fenêtre que l’on ouvre, et non d’un panneau toujours présent.

L’aperçu complet, c’est l’export avant qu’il soit écrit. Il s’agit d’une seule et même page, construite une fois : ce que montre cette fenêtre est le fichier qu’écrit Exporter en HTML, à une ligne près — celle qui permet à la fenêtre de trouver vos images sur votre disque, et que l’export omet parce qu’elle révélerait au lecteur l’emplacement du fichier.

Côte à côte

Aperçu en direct Aperçu complet Exporter en HTML Export, dessiné par le navigateur
Où à côté du texte ou à sa place dans sa propre fenêtre un fichier .html un fichier .html
Votre feuille de style non — le thème de l’éditeur oui, à l’identique oui, à l’identique oui, à l’identique
Suit la frappe à chaque touche à chaque pause — —
Formules $…$ le TeX tapé dessinées, en SVG dessinées, en SVG dessinées par MathJax à l’ouverture
Diagrammes mermaid le code source dessinés, en SVG dessinés, en SVG dessinés par mermaid.js à l’ouverture
Encadrés > [!TIP] une citation avec leur icône, repliables avec leur icône, repliables avec leur icône, repliables
Inclusions ![[note]] un lien la note, insérée la note, insérée la note, insérée
Coloration du code oui oui oui oui
Besoin du réseau non non non oui, pour le rendu
Mémoire rien de plus environ 117 Mo tant qu’il est ouvert — —

Les deux exports ne diffèrent que par qui dessine les formules et les diagrammes. L’export ordinaire les dessine ici : la page n’a besoin de rien — ni réseau ni script — et ressemble exactement à l’aperçu complet. Le second les laisse sous forme de TeX et de code mermaid, et inscrit dans la page l’adresse de deux scripts : le navigateur du lecteur télécharge alors MathJax et mermaid.js pour les dessiner. Les formules sont plus soignées et tout mermaid est disponible, mais la page contacte le serveur de quelqu’un à chaque ouverture.

Lequel utiliser

  • Pour écrire : l’aperçu en direct. Il suit le rythme, et il montre fidèlement la structure — titres, listes, tableaux, liens, mise en valeur —, c’est-à-dire ce qu’on vérifie en écrivant.
  • Pour voir le rendu tel qu’un autre le verra : l’aperçu complet. Votre feuille de style, vos images à leur taille, les formules et les diagrammes tels qu’ils seront dessinés.
  • Pour l’envoyer : Exporter en HTML, images incluses dans la page — vous obtenez un seul fichier, qui fonctionne partout et hors ligne. Imprimez-le depuis un navigateur pour en faire un PDF.
  • Pour publier des formules irréprochables, ou un diagramme que l’éditeur ne sait pas dessiner : l’export dessiné par le navigateur.

Pourquoi pas un seul moteur

Un moteur unique devrait être à la fois assez rapide pour se redessiner à chaque frappe et un moteur de navigateur complet. Ces deux exigences s’opposent : un moteur de navigateur dessine vite une page mais démarre lentement, et occupe de la mémoire que vous le regardiez ou non. L’éditeur garde donc un aperçu permanent léger et honnête sur ses limites, et met l’aperçu fidèle à portée de raccourci, sans qu’il coûte quoi que ce soit tant que vous ne l’ouvrez pas.

Et le réseau

L’éditeur ne télécharge jamais rien par lui-même — ni pour un aperçu, ni pour un export. Une image à une adresse https:// reste cette adresse : dans l’aperçu complet, c’est son texte alternatif qui s’affiche, et elle se charge chez quiconque ouvre la page exportée avec une connexion. La seule page qui contacte un serveur est l’export dessiné par le navigateur, et c’est alors le navigateur du lecteur qui télécharge les deux scripts dont les adresses sont dans vos réglages (export_mathjax_url, export_mermaid_url) — jamais cet éditeur. Pour en savoir plus : L’aperçu complet et Exporter en HTML.