Chaque section est une tâche, du début à la fin. Pour ce que fait une fonction en entier, voir le Guide d’utilisation.

Installer l’éditeur, et ce qu’il lui faut

Prérequis

Kaivalya Editor fonctionne sous Linux, avec Wayland ou X11, et dessine avec la carte graphique via Vulkan — n’importe quel bureau de ces dix dernières années en dispose. Tout le reste est facultatif : l’éditeur s’ouvre sans, et la fonction qui en a besoin le signale quand vous la demandez.

À installer Pour Sans
git récupérer, pousser, rebaser et changer de branche dans le panneau git le panneau affiche toujours les modifications, les différences, les commits et l’historique — lus sans git —, mais ces quatre boutons échouent en expliquant pourquoi
enchant-2 Vérifier l’orthographe la commande signale qu’enchant-2 manque
un dictionnaire hunspell par langue dans laquelle vous écrivez Vérifier l’orthographe dans cette langue la commande indique le dictionnaire qu’elle cherchait
JetBrainsMonoNL Nerd Font la police par défaut du texte la police à chasse fixe de votre bureau est utilisée à la place, et la barre d’état le signale une fois

Sous Ubuntu ou Debian :

sudo apt install git enchant-2 hunspell-fr hunspell-en-us

Ajoutez le paquet hunspell-… de chaque langue dans laquelle vous écrivez — hunspell-en-gb, hunspell-de-de, hunspell-es… La langue de vérification d’un document est le lang: de son en-tête (lang: fr), ou à défaut la langue de l’éditeur.

La police vient de Nerd Fonts : téléchargez JetBrainsMono, placez les fichiers JetBrainsMonoNLNerdFontMono-*.ttf dans ~/.local/share/fonts/, puis lancez fc-cache -f. Pour une autre police, il suffit d’un réglage — voir Modifier un réglage et font_family.

Rien d’autre n’est nécessaire à l’utilisation : l’aperçu complet, les formules, les diagrammes, les formateurs et la police d’émojis sont intégrés à l’éditeur.

L’installer

Depuis le paquet — Ubuntu 24.04 et suivantes

Chaque version propose un .deb à côté de ses notes, kaivalya-editor_<version>_amd64.deb. Téléchargez-le, puis :

sudo apt install ./kaivalya-editor_1.0.0_amd64.deb

apt installe ce dont il a besoin en même temps, et suggère git et enchant-2. L’éditeur apparaît ensuite dans vos applications. sudo apt remove kaivalya-editor le désinstalle ; vos réglages restent dans ~/.config/kaivalya-editor/. Le paquet est construit sous Ubuntu 24.04 : il s’installe sur cette version et les suivantes, pas sur les plus anciennes — pour celles-là, compilez-le depuis les sources.

Depuis l’archive de la version — toute distribution

Chaque version propose aussi kaivalya-editor-<version>-linux-x86_64.tar.gz et son .sha256. Vérifiez-la, décompressez-la, puis lancez son installateur :

sha256sum -c kaivalya-editor-1.0.0-linux-x86_64.tar.gz.sha256
tar xzf kaivalya-editor-1.0.0-linux-x86_64.tar.gz
cd kaivalya-editor-1.0.0-linux-x86_64 && ./install.sh

L’installation se fait pour vous seul, dans ~/.local ; PREFIX=/usr/local ./install.sh avec sudo l’installe pour tout le monde. Construite sous Ubuntu 24.04, elle demande une bibliothèque C au moins aussi récente (glibc 2.39) : toute distribution de 2024 ou plus récente.

Depuis les sources

L’éditeur peut aussi se compiler à partir de ses sources, ce qui demande une commande, et un peu de patience la première fois.

  1. Les outils de compilation, une fois pour toutes :

    sudo apt install build-essential pkg-config cmake clang mold \
  libwayland-dev libxkbcommon-dev libxkbcommon-x11-dev libvulkan-dev \
  libasound2-dev libfontconfig-dev libssl-dev libzstd-dev
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y

  2. Dans une copie du dépôt :

    make install

    La première compilation prend une dizaine de minutes ou plus ; les suivantes sont rapides. L’installation se fait pour vous seul, dans ~/.local — sans droits d’administrateur —, avec l’entrée du lanceur et l’icône. Appuyez sur Super et tapez Kaivalya.

make uninstall désinstalle une version installée ainsi et laisse vos réglages dans ~/.config/kaivalya-editor/.

Vérifier que tout est là

  • L’orthographe : ouvrez un fichier markdown et lancez Vérifier l’orthographe depuis le panneau markdown. Des mots soulignés signifient qu’enchant et le dictionnaire sont trouvés ; sinon, un message de la barre d’état indique ce qui manque.
  • git : dans un projet qui a un dépôt distant, cliquez sur Récupérer dans le panneau git.
  • La police : au démarrage, la barre d’état le signale si font_family désigne une police qui n’est pas installée.

Windows

Windows n’est pas pris en charge, et il n’y a rien à télécharger pour ce système. Le code compile pour Windows, et un guide pour essayer vous-même — non testé, avec ce qui est connu pour ne pas fonctionner (pas de correcteur orthographique, pas de Corbeille, pas d’installateur) — se trouve dans la documentation technique : Compiler sous Windows.

Choisir une feuille de style

Un document markdown mis en forme, c’est du HTML et une feuille de style. L’éditeur en fournit trois, et celle de GitHub est utilisée par défaut — mais un document écrit pour une charte graphique doit se lire avec cette charte, et tout l’intérêt d’un aperçu est de voir ce qu’un autre verra.

Un document peut donc trouver sa feuille de style de quatre façons, essayées dans l’ordre : la première qui répond l’emporte.

1. Celle que vous choisissez en lisant

À droite de la barre d’état figure le nom de la feuille de style avec laquelle le document est affiché. Cliquez dessus — ou ouvrez la liste en haut du panneau markdown — pour voir tout ce que vous pouvez choisir :

  • Automatique, qui n’impose rien et laisse décider le fichier et son dossier. C’est le point de départ de tout document.
  • Celle fournie avec l’éditeur, choisie explicitement. Ce n’est pas la même chose qu’Automatique : elle prend le pas sur un document qui désigne sa propre feuille de style. C’est ainsi qu’on lit la charte de quelqu’un d’autre en présentation sobre, sans modifier son fichier.
  • Tout le contenu de votre dossier de feuilles de style, par nom — les trois fournies et tout ce que vous y avez ajouté.
  • Toutes les feuilles de style du projet, par nom, avec leur chemin en dessous.
  • Choisir une feuille de style…, pour une feuille qui se trouve hors du projet — c’est le cas d’une seule charte partagée par vingt dépôts.

Ce choix appartient au document, pas à la fenêtre : deux onglets, deux réponses, et l’onglet que vous ne regardez pas garde la sienne.

Et il est mémorisé pour ce fichier. Choisissez une feuille de style, fermez l’onglet, rouvrez le fichier la semaine suivante : c’est toujours elle. L’information est gardée dans la session du projet, avec les fichiers ouverts et la position du curseur — rien n’est écrit dans votre document, car une ligne css: est une déclaration que verra toute personne ouvrant le fichier, et c’est à vous de l’écrire. Il s’agit ici d’une note que l’éditeur garde sur la façon dont vous le lisez.

Deux conséquences à connaître :

  • Choisir Automatique efface la note, au lieu de retenir que vous n’avez pas d’avis. Cette entrée rend la main au fichier et à son dossier ; un éditeur qui noterait « pas d’avis » continuerait de les contredire indéfiniment.
  • C’est propre à chaque projet. La session est l’endroit où l’éditeur garde ce que vous faisiez, et un fichier ouvert hors de tout projet n’a pas de session où le garder. Pour un choix qui voyage avec le fichier — sur une autre machine, chez quelqu’un d’autre —, c’est la ligne css: ci-dessous qu’il faut utiliser.

2. L’en-tête du document

---
css: ./charte.css
---

# Le document

Le chemin est relatif au document. Il voyage avec le fichier, et toute personne qui l’ouvre peut le voir : c’est donc le bon endroit pour dire « ce document s’affiche ainsi », plutôt que « il se trouve que je le lis ainsi ».

3. Une règle pour tout un dossier

Les règles d’un projet se trouvent dans .kaivalya/project.toml, dans un dossier .kaivalya à sa racine. La feuille de style d’un dossier y est une entrée, désignée par son chemin :

[[css]]
path = ""            # tout le projet
css = "charte.css"

[[css]]
path = "notes/"      # ce dossier et tout ce qu'il contient
css = "notes.css"

C’est la règle dont le path est le plus long qui l’emporte : une règle pour un dossier prend le pas sur celle de tout le projet. La feuille de style est cherchée d’abord dans .kaivalya/styles/ — les feuilles propres au projet —, puis à partir de la racine du projet ; un chemin absolu est pris tel quel. Une clé inconnue de l’éditeur est ignorée plutôt que refusée : un fichier écrit pour une version plus récente répond toujours à ce que celle-ci sait demander. Le même fichier contient le commit automatique du projet.

Les feuilles de style propres au projet vont dans .kaivalya/styles/. Le sélecteur de la barre d’état les liste en premier, puis les vôtres ; si l’une des vôtres porte le même nom de fichier, elle n’est pas listée : celle du projet l’emporte.

Seul ce fichier est lu. Un fichier .kaivalya — l’ancienne forme, qu’on pouvait mettre dans n’importe quel dossier avec des lignes css: charte.css — et .kaivalya-style ne sont plus lus : reportez ce qu’ils contenaient dans project.toml et supprimez-les. Si un projet contient encore un fichier .kaivalya, l’éditeur le signale à l’ouverture.

L’éditeur peut l’écrire pour vous, avec chaque clé expliquée en commentaire : Projet › Écrire le fichier du projet. Tout y est commenté : il ne fait rien tant que vous ne décommentez pas une ligne — et un fichier déjà présent est ouvert, pas remplacé.

4. Celle fournie avec l’éditeur

Rien d’autre n’a répondu : le document est affiché avec la feuille par défaut, désignée par un nom dans votre fichier de réglages et cherchée dans votre dossier de feuilles de style.

markdown_stylesheet = "github-light"  # la valeur par défaut
# markdown_stylesheet = "github"      # la paire, qui suit votre thème
# markdown_stylesheet = "kaivalya"    # celle de l'éditeur

Le dossier des feuilles de style

~/.config/kaivalya-editor/styles/, à côté de vos thèmes et selon les mêmes règles. L’éditeur y écrit les feuilles qu’il fournit à chaque démarrage, et ne touche jamais au reste :
github-light.css, github-dark.css celles de GitHub, utilisées par défaut
kaivalya.css celle de l’éditeur : une colonne en police à empattements, les deux palettes dans un seul fichier

Celle de GitHub, parce que c’est là qu’on lit un fichier markdown. Elle vient de github-markdown-css — GitHub ne publie pas la feuille de style de son site, et celle-ci est générée à partir d’une page qu’il a affichée.

Elle est dérivée de ce fichier, sans lui être identique, et elle ne suit pas ses nouvelles versions. Trois règles diffèrent, chacune marquée dans le fichier par le numéro du signalement qui l’a modifiée :

  • une liste dans une liste numérotée demandait des chiffres romains, que le moteur de l’aperçu dessine comme un carré vide : elle demande désormais des lettres ;
  • trois règles sont ajoutées pour que le triangle d’un encadré repliable soit bien placé et pivote à l’ouverture — GitHub n’a rien de tel, sa feuille de style n’a donc pas de règle pour cela ;
  • une règle est ajoutée pour centrer une image seule dans son paragraphe.

Cherchez F95, F102 ou F130 dans le fichier avec grep : chaque résultat est l’une d’elles. La licence et la mention d’origine sont intactes, en tête de chaque fichier. La largeur et les marges de la colonne, que cette feuille de style laisse volontairement de côté, sont fournies par l’aperçu.

Un nom, pas un chemin

markdown_stylesheet attend un nom, cherché de deux façons :

  1. <nom>-light.css ou <nom>-dark.css, selon votre thème ;
  2. <nom>.css.

Une seule règle couvre ainsi les deux façons dont une feuille de style peut suivre un thème. Celle de GitHub tient en deux fichiers, un par thème, car c’est ainsi qu’elle est publiée. Celle de l’éditeur est un seul fichier qui contient les deux palettes, choisies par un attribut data-theme que la page définit. Les vôtres fonctionnent dans les deux cas : déposez charte.css dans le dossier et réglez markdown_stylesheet = "charte", ou déposez la paire.

Une feuille de style que vous avez écrite est utilisée exactement telle quelle. Elle n’est pas adaptée au thème sombre, et ne le sera jamais : deviner les couleurs de quelqu’un, c’est le meilleur moyen de rendre illisible une présentation soignée. C’est aussi pourquoi celle de GitHub est fournie en deux fichiers, plutôt qu’en un seul que l’éditeur recolorerait.

Si le dossier n’existe pas

L’éditeur garde une copie des trois feuilles dans son exécutable et l’utilise. Un aperçu sans aucune mise en forme serait un échec bien pire que vingt kilo-octets de plus dans un programme : le dossier est donc ce que vous modifiez, pas ce dont l’éditeur dépend.

Quand une règle ne mène à rien

La barre d’état l’indique — le nom, suivi de introuvable, dans la couleur qu’elle réserve à ce qui demande votre attention. L’éditeur ne revient pas en silence à la feuille par défaut : une faute de frappe dans une ligne css: qui ne produirait aucun effet visible serait une faute que personne ne retrouverait.

Coller une capture d’écran

Faites une capture d’écran avec l’outil de votre bureau — sous GNOME, Impr. écran puis Copier dans le presse-papiers —, placez le curseur à l’endroit voulu et appuyez sur Ctrl+Alt+V. Vous pouvez aussi utiliser Coller une image dans la section Document du panneau markdown.

Deux choses se produisent :

  1. L’image est enregistrée dans un fichier, à côté de votre document.
  2. Un lien markdown vers ce fichier est inséré au curseur, avec le nom du fichier comme texte alternatif : ![notes-1](images/notes-1.png).

Une seule annulation retire le lien et vous ramène où vous étiez, comme pour toutes les autres commandes. Le fichier, lui, reste en place : supprimer l’image de quelqu’un parce qu’il a appuyé sur Ctrl+Z, ce n’est pas le rôle d’un éditeur.

Où va le fichier

À côté du document, dans un dossier défini par ce réglage :

paste_image_folder = "images"

Le dossier est créé au premier collage. Avec la valeur "", le fichier est placé directement à côté du document, et le lien ne contient pas de dossier : pratique pour une note et une capture, beaucoup moins pour une centaine.

Comment il s’appelle

Le nom du document suivi du plus petit numéro libre : notes-1.png, puis notes-2.png, puis notes-3.png.

Un numéro plutôt qu’un horodatage, et c’est voulu : un nom comme notes-20260907-143012.png est illisible dans un lien, et de toute façon une deuxième capture n’écrase jamais la première.

L’extension correspond à ce qui se trouvait réellement dans le presse-papiers — le plus souvent du PNG, mais certains outils fournissent du JPEG ou du WebP, et le fichier est nommé en conséquence.

Déposer une image

Faites glisser un fichier image depuis le gestionnaire de fichiers sur un document markdown : il est lié au curseur — plusieurs à la fois si besoin, un par ligne, chacun avec son nom comme texte alternatif. Une image qui se trouve déjà à côté du document, ou dans un dossier en dessous, est liée là où elle est. Une image venue d’ailleurs est copiée dans le même dossier que les images collées, sous son propre nom — chat-2.png si chat.png est déjà pris.

Tout autre fichier déposé sur le texte — ou une image déposée sur un fichier qui n’est pas du markdown — s’ouvre dans un onglet.

Quand ça ne marche pas

Dans chacun de ces cas, la barre d’état l’explique au lieu de ne rien faire :

  • Il n’y a pas d’image dans le presse-papiers. Vous avez copié du texte, un nom de fichier, ou rien du tout. Certains outils de capture placent un chemin dans le presse-papiers plutôt qu’une image : faites alors glisser le fichier, ou copiez l’image elle-même.
  • Le document n’a jamais été enregistré. Il n’a pas encore d’emplacement, donc pas de « à côté ». Enregistrez-le d’abord.
  • Impossible d’écrire dans le dossier. Le message indique lequel et pourquoi.

Créer, renommer et supprimer

Un nouveau document

Ctrl+N, ou Fichier › Nouveau fichier. Un onglet s’ouvre dans la fenêtre où vous êtes, mais rien n’est écrit sur le disque : un document qui n’a pas encore de nom n’a pas encore d’emplacement. Ctrl+S vous demande où l’enregistrer, et la fenêtre s’ouvre à la racine du projet (le dossier d’où l’éditeur a été lancé, sans projet ouvert). Enregistrer sous sur un fichier qui a déjà un nom s’ouvre à côté de lui.

C’est la différence avec le Nouveau fichier de l’explorateur, décrit ci-dessous, qui sait déjà où le créer.

Depuis l’explorateur

Un clic droit sur n’importe quelle ligne propose quatre actions : Nouveau fichier, Nouveau dossier, Renommer et Supprimer.

L’emplacement est celui auquel on s’attend : à l’intérieur du dossier sur lequel vous avez cliqué, ou à côté du fichier.

La petite fenêtre de saisie

Les trois premières actions ouvrent la même petite fenêtre : le chemin du projet, puis un champ contenant un chemin relatif à ce projet, et enfin Annuler et Créer.

Les deux mis bout à bout donnent le chemin exact : vous savez toujours où le fichier va être créé. Et comme il s’agit d’un champ modifiable plutôt que d’un simple libellé, cela apporte trois avantages :

  • Une erreur de ligne se corrige, sans tout recommencer. Vous avez cliqué sur le mauvais dossier ? Modifiez le chemin.
  • Les dossiers intermédiaires sont créés. Tapez notes/2026/aujourdhui.md et les deux dossiers apparaissent, avec le fichier dedans, en une seule fois.
  • Le curseur est déjà au bon endroit. Pour créer, il est placé après le dossier. Pour renommer, seul le nom est sélectionné, pas l’extension : notes.md devient todo.md sans retaper .md.

Un nouveau fichier s’ouvre dès sa création, puisque c’est pour cela que vous l’avez créé. Un nouveau dossier, lui, n’a rien à ouvrir : il est simplement mis en évidence dans l’explorateur.

Quand c’est refusé

Dans chacun de ces cas, la fenêtre reste ouverte avec votre saisie, pour que la correction ne prenne qu’une touche :

  • Le nom est déjà pris. Rien n’est écrasé, et rien n’est ouvert à la place : l’un comme l’autre masquerait le fait que vous vouliez créer quelque chose de nouveau.
  • Le chemin sort du projet. Un ../ qui remonte au-dessus du dossier ouvert est refusé, de même qu’un chemin absolu. Le champ est libre pour pouvoir corriger une erreur de clic ; c’est la contrepartie.
  • Impossible d’écrire dans le dossier. Le message indique lequel et pourquoi.

Renommer

Renommer permet aussi de déplacer : le champ contient un chemin, donc transformer notes.md en docs/notes.md le range dans docs.

Si le fichier est ouvert, son onglet suit — l’onglet, le titre de la fenêtre et la session restaurée. Rien n’est enregistré au passage : un fichier qui contenait des modifications non enregistrées les garde, et reste marqué comme modifié.

Renommer vers un nom déjà existant est refusé. Ce refus compte plus que les autres : renommer un fichier par-dessus un autre détruirait le second sans prévenir.

Supprimer

L’éditeur demande d’abord confirmation, en nommant précisément ce qu’il va supprimer — par son chemin et, pour un dossier, avec le nombre d’éléments qu’il contient.

L’élément part dans la corbeille de votre bureau, il n’est pas effacé définitivement. L’option Restaurer de votre gestionnaire de fichiers le remet donc à sa place. Il n’y a pas d’annulation dans l’éditeur, et il n’y en aura pas : la corbeille en tient lieu.

Deux choses que l’éditeur refuse :

  • Un fichier situé sur un autre système de fichiers que votre dossier personnel n’est pas supprimé, et l’éditeur vous le dit. Mettre à la corbeille d’un système de fichiers à l’autre demande une corbeille sur ce système, que l’éditeur ne crée pas. Faute d’annulation, refuser est la solution la plus sûre.
  • L’onglet d’un fichier supprimé se ferme sans proposer de l’enregistrer : ce serait une question absurde pour un fichier que vous venez de jeter.

Exporter en HTML

Exporter en HTML…, dans la section Document du panneau markdown, écrit le document sous forme de page web autonome : votre feuille de style, vos titres, vos tableaux, et vos diagrammes mermaid et formules dessinés comme de vraies images.

C’est la page même qu’affiche l’aperçu complet : ce que vous y voyez est ce que vous obtenez — sauf si vous en décidez autrement dans la fenêtre qui s’ouvre d’abord.

Les trois questions posées

Elles portent sur cet export-là : elles vous sont donc posées au moment d’exporter, plutôt que rangées dans votre fichier de réglages. La fenêtre s’ouvre sur la réponse raisonnable à chacune et ne retient rien : un export fait sans y penser est un export qui n’a besoin de rien et ressemble à l’aperçu.

Images dans la page

Cochée — par défaut —, cette option intègre chaque image à la page elle-même. Vous obtenez un fichier qui est vraiment un seul fichier : vous pouvez l’envoyer par courriel, le déplacer n’importe où, il fonctionnera toujours. Il pèse environ un tiers de plus que les images d’origine.

Décochée, elle copie les images dans un dossier à côté de la page, à leur taille, et un champ apparaît pour le nom de ce dossier (img par défaut). Un fichier plus un dossier : c’est ce qu’il vous faut quand les images sont lourdes, ou que la page est destinée à un site.

Mathématiques et diagrammes dessinés par le navigateur

Décochée — par défaut —, les deux sont dessinés ici, en SVG, avant l’écriture du fichier. La page n’a alors besoin de rien : ni réseau, ni script, ni police web.

Cochée, les formules restent en TeX et les diagrammes sous leur forme source, et la page charge MathJax et mermaid.js pour les dessiner à l’ouverture. Cochez-la quand :

  • les formules doivent être parfaites. MathJax est l’implémentation de référence de la mise en page TeX — c’est ce qu’utilise GitHub —, et le moteur de l’éditeur, il faut l’avouer, n’est pas tout à fait à ce niveau ;
  • le diagramme a besoin de quelque chose que mermaid.js sait faire et pas le moteur de l’éditeur — un type de diagramme, un thème, une interaction ;
  • la page est destinée à un site qui charge déjà ces scripts.
Décochée Cochée
S’ouvre sans réseau oui non
Demande un script au serveur de quelqu’un d’autre non oui
Ressemble à l’aperçu oui non — formules plus soignées, autre rendu mermaid
Code coloré oui oui
S’imprime en PDF oui oui, une fois les scripts exécutés

Le code est coloré par l’éditeur dans les deux cas ; c’est la seule chose que l’on ne demande pas aux scripts de refaire. Les couleurs sont inscrites dans la page : un bloc de code a le même aspect dans l’aperçu, dans un fichier exporté et sur papier.

L’origine de ces scripts est à vous de choisir, puisque c’est le navigateur de votre lecteur qui ira les chercher. Ces deux adresses restent dans le fichier de réglages, car elles concernent tous les exports et pas seulement celui-ci :

export_mathjax_url = "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js"
export_mermaid_url = "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs"

Faites-les pointer vers votre propre serveur, une copie sur un intranet ou une autre version. Par défaut, ce sont les CDN des deux projets, figés sur une version majeure : une page exportée aujourd’hui ne doit pas être redessinée l’an prochain par quelque chose que personne n’a vérifié. Pour MathJax, c’est la version SVG qui est utilisée : elle n’embarque aucune police web, et la page s’imprime telle qu’elle s’affiche.

Un bouton retour sur chaque note

Décochée — par défaut —, chaque note de bas de page reçoit une flèche par endroit où elle est appelée, chacune indiquant la section à laquelle elle ramène. C’est tout ce que permet le balisage seul, sans script.

Cochée, la note reçoit une seule flèche qui vous ramène à l’appel sur lequel vous avez cliqué, ce qui demande quinze lignes de script dans la page. Cette flèche reste un lien ordinaire vers le premier appel : un lecteur dont les scripts sont désactivés arrive quand même à un endroit sensé.

Utile pour un document dont les notes sont appelées à plusieurs endroits ; inutile quand chacune ne l’est qu’une fois, puisque les deux flèches se confondent.

Feuille de style

La page part de la feuille de style avec laquelle le document est affiché, dont le nom figure sur la ligne. Cliquez dessus pour voir les autres : celle fournie avec l’éditeur, celles de votre dossier de feuilles de style, et les fichiers .css du projet — la même liste que dans le sélecteur du panneau markdown. Ce choix ne vaut que pour cet export : le document continue d’être affiché comme avant, et le prochain export repartira de sa propre feuille de style.

L’éditeur, lui, ne télécharge toujours rien. Les adresses sont inscrites dans la page ; c’est le navigateur de la personne qui l’ouvre qui va chercher les scripts. S’ils n’arrivent jamais, la page reste lisible : les formules sont là en TeX et le diagramme sous forme de texte — c’est précisément pour cet échec-là que cette forme a été choisie.

Tout un projet

Projet › Exporter le projet en HTML… pose les mêmes questions — images, dessin par le navigateur, flèches des notes, feuille de style —, puis demande un dossier. Chaque fichier markdown du projet y devient une page, au même chemin : docs/installation.md devient docs/installation.html.

  • Les liens entre pages continuent de fonctionner. Un lien vers un autre fichier markdown du projet, ou un [[lien wiki]], pointe vers la page de ce fichier.
  • Un lien vers tout autre fichier est laissé tel quel, et l’éditeur vous indique combien il y en a à la fin : un lien vers rapport.pdf ne mène à rien dans le dossier exporté, à moins d’y copier le fichier.
  • Ce que git ignore n’est pas exporté, quoi qu’affiche l’explorateur, pas plus que le dossier d’export lui-même s’il se trouve dans le projet.
  • La feuille de style est réglée au départ sur Comme chaque document est affiché : chaque page reçoit celle que lui donnent son en-tête, la règle de son dossier ou votre propre choix. Choisissez-en une dans la liste, et toutes les pages l’utiliseront.

Trois choses qu’il ne fait pas

Il ne laisse aucune trace de votre machine. L’aperçu contient une balise <base> qui pointe vers le dossier du document, pour que ![](schema.png) soit trouvé pendant la lecture. L’export, non : cette ligne ne servirait à rien à la personne qui ouvre la page, et lui révélerait l’emplacement du fichier sur votre disque.

Il ne télécharge rien. Une image à une adresse http:// ou https:// reste cette adresse — l’éditeur ne fait aucune requête réseau, et l’export n’est pas le moment de commencer. Elle se chargera pour quiconque dispose d’internet, comme aujourd’hui. (L’export dessiné par le navigateur inscrit deux adresses de scripts dans la page : c’est le navigateur du lecteur qui les télécharge, pas cet éditeur.)

Il ne masque pas une image manquante. Une image citée mais absente le reste : l’export affiche une image cassée plutôt que de la faire disparaître discrètement. Un trou visible est un trou que l’on peut combler.

Et le PDF ?

Il n’y a pas d’export PDF, et c’est voulu. Exportez la page et imprimez-la depuis un navigateur : Ctrl+P, Enregistrer au format PDF, et vous obtenez une vraie pagination, des marges et des sauts de page, grâce à un outil qui travaille sur ce problème depuis vingt ans.

Modifier un réglage

Les réglages tiennent dans un fichier texte, et chaque option y est expliquée.

Pour vous

  1. Éditeur › Fichier de réglages, ou Ctrl+,. Le fichier ~/.config/kaivalya-editor/settings.toml s’ouvre ; il est créé s’il n’existe pas encore.

  2. Modifiez une valeur, ou décommentez une ligne d’exemple :

    font_size = 18.0
soft_wrap = false
todo_tags = ["TODO", "FIXME", "NOTE"]

  3. Enregistrez, puis redémarrez l’éditeur : les réglages sont lus au démarrage.

Supprimer une ligne revient à reprendre la valeur par défaut. Éditeur › Réinitialiser le fichier de réglages rétablit tout le fichier par défaut et garde le vôtre à côté, sous le nom settings.toml.bak. Une erreur dans le fichier n’empêche jamais l’éditeur de s’ouvrir : il démarre avec les valeurs par défaut et vous indique ce qui ne va pas.

Pour un seul projet

  1. Projet › Réglages du projet ouvre le fichier .kaivalya/settings.toml du projet, en le créant si besoin.

  2. N’y écrivez que ce qui change pour ce projet, avec les mêmes noms :

    # .kaivalya/settings.toml
tab_size = 4
todo_tags = ["TODO", "FIXME", "HACK"]

  3. Enregistrez : le changement s’applique immédiatement, et à chaque ouverture du projet. Vos réglages habituels reviennent dès que vous ouvrez un autre projet.

Si le fichier contient une option que l’éditeur ne connaît pas, la barre d’état la signale, et tout le reste s’applique quand même.

Les options disponibles

Tous les réglages les présente une par une, avec leur explication et leur valeur par défaut — le même texte que dans le fichier.

Ajouter un thème

Un thème tient dans un seul fichier JSON. Pour créer le vôtre, copiez un thème fourni sous un autre nom.

Pour tous vos projets

  1. Ouvrez le dossier des thèmes, ~/.config/kaivalya-editor/themes/.

  2. Copiez le thème le plus proche de ce que vous voulez — par exemple kaivalya-dark.json — sous un nom qui ne commence pas par kaivalya-, comme foret.json. Les fichiers kaivalya-* sont réécrits à chaque démarrage de l’éditeur : vos modifications n’y survivraient pas. Les vôtres, en revanche, ne sont jamais touchés.

  3. Dans votre copie, remplacez le "name" du haut du fichier, ainsi que le "name" du thème dans "themes", par le nom de votre choix — "Forêt".

  4. Modifiez les couleurs. Chaque clé est expliquée dans kaivalya-theme.schema.json, dans le même dossier ; un éditeur qui lit la ligne $schema du fichier — celui-ci compris — affiche cette explication pendant la saisie.

  5. Dans votre fichier de réglages (Ctrl+,), choisissez le thème par son nom :

    theme = "Forêt"

Le dossier est surveillé : enregistrer le fichier du thème recolore aussitôt l’éditeur. La ligne theme de vos réglages, elle, prend effet au prochain démarrage.

Pour un seul projet

Placez le même fichier dans le projet, dans .kaivalya/themes/. Il s’ajoute aux vôtres tant que le projet est ouvert, et l’emporte sur l’un des vôtres qui porterait le même nom. Pour que le projet l’utilise, indiquez-le dans les réglages propres au projet — Projet › Réglages du projet —, qui s’appliquent dès l’enregistrement :

# .kaivalya/settings.toml
theme = "Forêt"

Toute personne qui ouvre le projet a son thème : il fait partie du projet et le suit partout, git compris.

Voir aussi

Ajouter une feuille de style

Une feuille de style détermine l’apparence d’un document dans l’aperçu complet et dans une page exportée. C’est un simple fichier .css, utilisé exactement tel que vous l’avez écrit. Choisissez la portée dont vous avez besoin.

Pour tous les documents

  1. Placez maison.css dans ~/.config/kaivalya-editor/styles/. Pour suivre le thème clair ou sombre, placez plutôt deux fichiers : maison-light.css et maison-dark.css.

  2. Dans votre fichier de réglages (Ctrl+,) :

    markdown_stylesheet = "maison"   # un nom, pas un chemin

Elle s’applique au prochain démarrage. D’ici là — ou pour l’essayer —, choisissez-la depuis le nom de la feuille de style dans la barre d’état, qui liste tout le contenu de ce dossier.

Pour un projet, ou l’un de ses dossiers

  1. Placez le CSS dans le dossier .kaivalya/styles/ du projet.

  2. Projet › Écrire le fichier du projet crée .kaivalya/project.toml, où chaque clé est expliquée ; ajoutez-y une règle :

    [[css]]
path = ""            # tout le projet
css = "maison.css"

[[css]]
path = "notes/"      # ce dossier, en remplacement de la règle ci-dessus
css = "notes.css"

Quand plusieurs règles s’appliquent à un document, c’est celle dont le path est le plus long qui l’emporte.

Pour un seul document

Indiquez-la dans l’en-tête du document, par un chemin relatif au document :

---
css: ./impression.css
---

Celle-ci voyage avec le fichier : quiconque l’ouvre obtient la même feuille de style.

Laquelle l’emporte

Celle choisie dans la barre d’état, puis le css: du document, puis la règle du dossier, puis markdown_stylesheet. Choisir une feuille de style explique chacune en détail.

Ajouter un modèle

Un modèle est un simple fichier markdown. Son nom est ce que vous tapez après /.

En créer un

  1. Créez le fichier :

    • pour tous vos projets, dans ~/.config/kaivalya-editor/templates/ — par exemple reunion.md ;
    • pour un seul projet, dans son dossier .kaivalya/templates/. À nom égal, c’est le modèle du projet qui l’emporte.

  2. Écrivez ce qui doit être inséré. Quatre marqueurs sont remplacés :

    # Réunion — {{date}}

Présents :

## Décisions

{{cursor}}
    {{date}} la date du jour, 2026-10-07
    {{time}} l’heure, 14:32
    {{title}} le nom du fichier du document, sans .md
    {{cursor}} l’endroit où placer le curseur ; sinon, à la fin

    Tout autre texte entre {{ }} est laissé tel quel.

  3. Dans n’importe quel fichier markdown, tapez /reunion puis Entrée.

Les dossiers sont relus à chaque ouverture de la palette : un modèle est disponible dès qu’il est enregistré, sans redémarrer.

Les ranger dans des dossiers

Les sous-dossiers de templates/ deviennent des groupes dans la palette — templates/jdr/pj.md apparaît sous Modèles › jdr › pj — et la recherche porte toujours sur tous les modèles, où qu’ils soient rangés.

Deux modèles fournis

name.md et mail.md sont écrits dans votre dossier de modèles au premier lancement, avec un nom et une adresse fictifs : remplacez-les par les vôtres, et /name et /mail les inséreront n’importe où. journal.md est le modèle de départ de La note du jour (Ctrl+Maj+J) — le réglage daily_note_template permet d’en choisir un autre.

Voir aussi