notabene

Commenter la doc rendue, l'agent corrige le Markdown

notabene affiche le Markdown ou le MDX d'un dépôt sous forme de site navigable, et chacun y commente la page rendue : un passage sélectionné, une page entière, un diagramme ou une image. Un agent IA lit ensuite ces commentaires, modifie les fichiers sources, marque chaque fil comme résolu et note dans un journal ce qui a changé et pourquoi. Le commentaire ancré remplace le prompt qui devait citer le passage et nommer la section pour que l'agent trouve le bon endroit ; l'article consacré à notabene revient sur ce problème.

notabene est un projet de Z29K, l'éditeur de ce site : le dépôt et le copyright du code sont au nom de z29k, et le paquet npm s'appelle @z29k/notabene.

Un fichier JSON par commentaire, versionné avec la doc

• Chaque commentaire est un fichier JSON rangé sous .notabene/, dans le dépôt plutôt que dans un SaaS ou une base de données : git fusionne les retours sans conflit et ils apparaissent dans les diffs de pull request.
• L'agent se contente de lire et d'écrire des fichiers, sans serveur, sans port et sans MCP. notabene init dépose la spécification dans .notabene/protocol.md et la signale dans AGENTS.md, que Codex CLI, Cursor, Gemini CLI ou Zed lisent au démarrage. Claude Code reçoit la même procédure sous forme de skill, via un plugin.
• L'ancre garde le texte cité, le texte qui l'entoure et le titre le plus proche ; l'agent s'en sert pour retrouver le passage dans la source avec une correspondance tolérante.
• En mode approbation (review: "approve"), l'agent propose sans rien résoudre. Chaque modification attend sur /review à côté de son vrai diff git, y compris quand un seul commentaire touche plusieurs pages, et un refus rouvre le fil avec sa raison, que l'agent lit à son passage suivant.
• notabene comments verify contrôle les statuts et les liens entre commentaires et journal, et renvoie un code d'erreur en cas d'anomalie : la commande peut bloquer une CI. notabene lint vérifie les liens internes contre les routes que le dernier build a réellement produites.
• Le site lui-même gère MDX et CommonMark/GFM, des diagrammes Mermaid commentables, une doc multilingue aux commentaires séparés par langue et l'export PDF. build --public en tire un site statique en lecture seule avec llms.txt, une recherche Pagefind en option et un workflow GitHub Pages fourni.

Revue sur le serveur de dev, versions encore en 0.x

Les commentaires ne s'écrivent que sur le serveur de dev. L'API qui enregistre les commentaires et l'éditeur intégré à la page n'existent que sous notabene dev, liés par défaut à 127.0.0.1. Ouvrir une revue à d'autres personnes passe par l'option --host, que la documentation réserve aux réseaux de confiance, de préférence avec un jeton NOTABENE_TOKEN. Aucun compte n'est géré : sur un hôte partagé, chaque visiteur saisit son nom et, s'il le veut, un e-mail. Le site public, lui, ne contient ni interface ni donnée de commentaire.

Node 22.12 ou plus récent et des fichiers suivis par git sont exigés. notabene lit du Markdown ou du MDX rangé dans un dépôt, et l'éditeur dans la page refuse d'écrire un fichier que git ne suit pas, sauf réglage contraire. Le PDF à signets de notabene pdf demande en plus Puppeteer, qui pilote un Chromium headless ; l'impression depuis le navigateur s'en passe.

Le projet se présente d'abord comme un protocole. Sa documentation promet des commentaires « façon Google Docs » conservés dans git, et le résume ainsi : le viewer est le support, le protocole est le produit. Le store .notabene est traité comme un contrat public versionné, aujourd'hui à la version 3 de son schéma, et chaque changement de format arrive avec un migrateur (notabene migrate).

La dernière version est la 0.17.0, du 12 octobre 2026. Elle fait passer le moteur de rendu à Astro 7. Les releases GitHub en comptent 27, de la 0.3.0 du 3 juillet 2026 à la 0.17.0.