Notation
Kristian Gaylord · Programmation · Apprentissage
Notation est un outil en ligne de commande gratuit et open source qui publie un dossier de fichiers Markdown dans Notion. Vous écrivez la documentation dans le dépôt, lancez une commande, et Notion la sert avec la recherche et l'IA intégrées.
À propos de Notation
About
Qu'est-ce que Notation
Notation est un utilitaire de terminal qui prend un dossier rempli de fichiers Markdown et le transvase dans une page Notion. Le projet est écrit en Rust et publié sous licence GPL-3.0. Une commande, notation ship --src, parcourt le dossier et reconstruit l'arborescence des pages dans Notion.
Le raisonnement est simple : une documentation appartient au code qu'elle décrit. Vous modifiez les fichiers .md dans la même pull request que la fonctionnalité, la relecture voit le diff, et l'intégration continue peut lancer la publication. Personne n'a besoin d'ouvrir un service séparé après une fusion.
Deux contraintes cadrent l'usage. Notion est la seule destination, donc la publication vise toujours une page qui vous appartient. Et la synchronisation va dans un seul sens, du Markdown vers Notion : le dépôt reste la source de vérité, et ce qui est tapé dans Notion ne remonte pas.
Pour commencer
- Installez le binaire avec le script shell de la page du projet. Il place l'exécutable dans
~/.notationet crée un fichier de configuration de départ à côté. - Créez dans Notion la page qui hébergera la documentation, avec un nom que vous pourrez recopier à l'identique dans la configuration.
- Générez une intégration interne dans Paramètres et membres, puis copiez son secret. Sur la page parente, ajoutez cette intégration via Connexions pour lui donner le droit d'écriture.
- Ouvrez
~/.notation/Notation.tomlet renseignez deux valeurs : lesecretde l'intégration et le titre deparent_page. - Lancez
notation ship --src /chemin/vers/docsdepuis le dépôt. Vérifiez le rendu dans Notion, puis partagez la page publiquement ou pointez un domaine dessus si vous voulez un site ouvert.
Informations sur le produit
Aperçu des tarifs, des plateformes compatibles et des performances de Notation.
Idéal pour
Les utilisateurs, tâches et cas d'usage où cet outil convient le mieux.
Utilisateurs
- Ingénieurs backend et plateforme
- Petites équipes produit sans site de documentation
- Équipes support, ventes et produit
Tâches
- Publier des références d'API
- Mettre à jour les guides d'accueil
- Transformer des runbooks internes en wiki
Cas d'usage
- Vous payez déjà Notion et ne voulez pas un deuxième abonnement de documentation. Notation ajoute l'étape de publication, rien de plus.
- Votre documentation a pris du retard parce que la mettre à jour demandait d'ouvrir un autre outil. Ramener la source dans le dépôt supprime ce détour.
- Vous voulez une documentation relue comme du code. Les fichiers étant du texte brut versionné, le circuit habituel de pull request s'en charge.
Fonctionnalités clés
Publier un dossier en une commande
notation ship --src parcourt le dossier source et écrit chaque fichier dans la page Notion configurée. Aucun build, aucun site généré à déployer : entre la fusion d'une modification et sa mise en ligne, il n'y a qu'une commande.
L'arborescence des dossiers devient celle des pages
Les dossiers deviennent des sous-pages et les sous-dossiers des sous-pages de second niveau. L'arbre visible dans l'éditeur est donc celui que le lecteur retrouve dans Notion. Renommer un dossier renomme la page correspondante à la publication suivante.
intro.md pour la page parente
Un fichier nommé intro.md à la racine du dossier écrit son contenu directement sur la page parente au lieu de créer une page enfant. La section obtient ainsi une vraie page d'accueil, avec du texte, des liens et du contexte, plutôt qu'un conteneur vide et une liste d'enfants.
Titre et emoji par page
Deux indicateurs en tête de fichier Markdown, --title et --emoji, fixent le nom et l'icône de la page dans Notion. Un fichier setup.md peut s'afficher comme « Getting Started » avec une fusée : les noms de fichiers restent pratiques pour la machine, les titres restent lisibles pour les humains.
Wiki interne ou site public
La même destination peut rester privée dans votre espace de travail ou être partagée comme site ouvert. Pour un domaine personnalisé, la documentation officielle renvoie vers Super comme couche front end, ce qui est aussi la façon dont notation.so est servi.
Recherche, IA et mise en forme Notion sans frais
Une fois le contenu dans Notion, vous héritez de son index de recherche, de ses réponses par IA, de sa table des matières et de son formatage par blocs. Chercher dans un gros corpus de documentation Markdown est un problème difficile, et ici c'est un autre qui le résout.
Avantages et inconvénients
Avantages
- Gratuit et open source sous GPL-3.0, sans sièges, paliers ni limite par page à surveiller.
- La documentation reste dans le dépôt : relecture de code, branches et intégration continue s'y appliquent sans réglage supplémentaire.
- L'installation est courte : poser le binaire, créer une intégration Notion, remplir deux valeurs.
- Les lecteurs travaillent dans Notion, donc la recherche, les commentaires et les réponses d'IA viennent avec l'outil que l'équipe garde déjà ouvert.
- Le rendu semble construit à la main dans Notion : un lecteur non technique ne devine pas que les pages sortent de Markdown.
Inconvénients
- La synchronisation est à sens unique. Ce qui est modifié dans Notion est écrasé à la publication suivante, donc le dépôt doit rester le seul endroit où l'on écrit.
- Les images exigent une URL publique, car les fichiers locaux ne sont pas envoyés. Vous hébergez le visuel ailleurs et collez le lien.
- Chaque personne a besoin d'un compte Notion, d'une page hôte et d'un jeton d'intégration interne : trois endroits où se tromper avant la première exécution réussie.
- Le projet est petit et son dernier commit date d'août 2024. Un changement cassant dans l'API Notion demanderait à quelqu'un de corriger le binaire, et le script d'installation ne prend pas Windows en charge.
Questions fréquentes
À publier du Markdown vers Notion en une passe. Vous gardez les fichiers .md dans un dépôt, lancez notation ship, et ils apparaissent sous forme d'arborescence dans la page Notion de votre choix.
Contenus associés
Découvrez des outils, des compétences et des articles liés à Notation.
Alternatives à Notation
Base Code
Base44 (Wix) · Programmation · ProductivitéBase Code est un environnement de développement cloud partagé signé Base44. Votre équipe décrit des modifications sur un dépôt GitHub dans le chat, les vérifie en aperçu et les renvoie sous forme de pull requests.
Google EmbeddingGemma 2
Google DeepMind · Rédaction · Image · ProgrammationGoogle EmbeddingGemma 2 est un modèle ouvert de 740 millions de paramètres qui transforme texte, code, images, audio et images vidéo en vecteurs d'un même espace de 768 dimensions, sur un téléphone ou un ordinateur portable.
GitGlow
GitGlow · Programmation · ProductivitéGitGlow est un client Git de bureau qui place votre code et les modifications de vos agents IA dans une même revue, pour savoir ce qui quitte votre machine avant de livrer.