Notation
Kristian Gaylord · Coding · Lernen
Notation ist ein kostenloses Open-Source-Kommandozeilentool, das einen Ordner mit Markdown-Dateien nach Notion bringt. Sie schreiben die Doku im Repository, führen einen Befehl aus, und Notion liefert sie mit Suche und KI aus.
Über Notation
About
Was ist Notation
Notation ist ein kleines Terminalwerkzeug, das ein Verzeichnis voller Markdown-Dateien in eine Notion-Seite schreibt. Das Projekt ist in Rust geschrieben und steht unter der GPL-3.0. Ein Befehl, notation ship --src, liest den Ordner und baut den Seitenbaum in Notion neu auf.
Der Gedanke dahinter: Notion-Dokumentation gehört zu dem Code, den sie beschreibt. Genau das meint Docs as Code. Sie ändern die .md-Dateien im selben Pull Request wie das Feature, die Review sieht den Diff, und die CI kann den Veröffentlichungsschritt ausführen. Niemand muss nach dem Merge einen zweiten Dienst öffnen.
Zwei Grenzen bestimmen den Einsatz. Notion ist das einzige Ziel, veröffentlicht wird also immer auf einer Seite, die Ihnen gehört. Und der Abgleich läuft nur in eine Richtung, von Markdown nach Notion. Das Repository bleibt die Quelle der Wahrheit, und was in Notion getippt wird, kommt nicht zurück.
Erste Schritte
- Installieren Sie die Binärdatei mit dem Shell-Skript von der Projektseite. Es legt die Datei in
~/.notationab und erzeugt daneben eine Grundkonfiguration. - Legen Sie in Notion die Seite an, die die Doku aufnehmen soll, und geben Sie ihr einen Namen, den Sie in der Konfiguration zeichengenau wiederholen können.
- Erstellen Sie unter Einstellungen und Mitglieder eine interne Integration und kopieren Sie deren Secret. Fügen Sie die Integration auf der übergeordneten Seite unter Verbindungen hinzu, damit sie Schreibrechte bekommt.
- Öffnen Sie
~/.notation/Notation.tomlund tragen Sie zwei Werte ein: dassecretder Integration und den Titel derparent_page. - Führen Sie
notation ship --src /pfad/zu/docsim Repository aus. Prüfen Sie das Ergebnis in Notion und teilen Sie die Seite öffentlich oder richten Sie eine eigene Domain darauf, wenn daraus eine Website werden soll.
Produktinformationen
Ein kurzer Überblick über Preise, unterstützte Plattformen und die Leistung von Notation.
Am besten für
Die Nutzer, Aufgaben und Szenarien, für die dieses Tool am besten passt.
Nutzer
- Backend- und Plattformentwickler
- Kleine Produktteams ohne Doku-Website
- Support, Vertrieb und Produkt
Aufgaben
- API-Referenzen veröffentlichen
- Onboarding-Guides aktuell halten
- Interne Runbooks in ein Wiki überführen
Szenarien
- Sie zahlen schon für Notion und wollen kein zweites Doku-Abo. Notation fügt den Veröffentlichungsschritt hinzu und sonst nichts.
- Ihre Doku ist veraltet, weil jede Aktualisierung einen Ausflug in ein anderes Werkzeug bedeutete. Die Quelle ins Repository zu holen spart diesen Weg.
- Sie wollen Doku wie Code reviewen. Weil die Quelldateien reiner Text unter Versionskontrolle sind, greift der normale Pull-Request-Ablauf.
Wichtigste Funktionen
Einen Doku-Ordner mit einem Befehl veröffentlichen
notation ship --src läuft durch das Quellverzeichnis und schreibt jede Datei in die eingestellte Notion-Seite. Es gibt keinen Build und keine generierte Website, die ausgeliefert werden müsste. Zwischen Merge und sichtbarer Änderung liegt ein Befehl.
Aus Ordnerstruktur wird Seitenstruktur
Verzeichnisse werden zu Unterseiten, Unterverzeichnisse zu Unterseiten der zweiten Ebene. Der Baum im Editor ist derselbe, den Leser in Notion sehen. Wird ein Ordner umbenannt, trägt die passende Seite beim nächsten Lauf den neuen Namen.
intro.md für die übergeordnete Seite
Eine Datei namens intro.md im Wurzelverzeichnis schreibt ihren Inhalt direkt auf die Elternseite, statt eine Kindseite anzulegen. Der Abschnitt bekommt damit eine Startseite mit Text, Links und Kontext statt eines leeren Containers mit einer Liste von Kindern.
Titel und Emoji pro Seite
Zwei Angaben am Kopf jeder Markdown-Datei, --title und --emoji, setzen Name und Symbol der Notion-Seite. Eine Datei setup.md kann als "Getting Started" mit Rakete erscheinen. Dateinamen bleiben maschinenfreundlich, die veröffentlichten Titel lesen sich sauber.
Internes Wiki oder öffentliche Website
Dasselbe Ziel kann privat im Workspace bleiben oder als offene Seite geteilt werden. Für eine eigene Domain verweist die offizielle Doku auf Super als Frontend, und so wird auch notation.so ausgeliefert.
Suche, KI und Formatierung von Notion ohne Aufpreis
Sobald der Inhalt in Notion liegt, erben Sie den Suchindex, die KI-Antworten, das Inhaltsverzeichnis und die Blockformatierung. Die Suche über einen großen Bestand an Markdown-Dokumentation ist ein hartes Problem, und hier kümmert sich jemand anderes darum.
Vor- und Nachteile
Vorteile
- Kostenlos und quelloffen unter GPL-3.0, ohne Sitze, Stufen oder Seitengrenzen zum Nachhalten.
- Die Doku bleibt im Repository, also gelten Codereview, Branches und CI ohne Zusatzarbeit.
- Die Einrichtung ist kurz: Binärdatei installieren, Notion-Integration anlegen, zwei Werte eintragen.
- Leser arbeiten in Notion, damit kommen Suche, Kommentare und KI-Antworten mit dem Werkzeug, das im Team ohnehin offen ist.
- Das Ergebnis wirkt in Notion handgebaut, technikferne Leser erkennen die Markdown-Herkunft nicht.
Nachteile
- Der Abgleich läuft nur in eine Richtung. Was in Notion bearbeitet wird, überschreibt der nächste Lauf, also muss das Repository der einzige Schreibort bleiben.
- Bilder brauchen eine öffentliche URL, weil lokale Dateien nicht hochgeladen werden. Sie hosten das Bild woanders und fügen den Link ein.
- Jede Person braucht ein Notion-Konto, eine Trägerseite und ein internes Integrationstoken. Drei Stellen, an denen vor dem ersten erfolgreichen Lauf etwas schiefgehen kann.
- Das Projekt ist klein, und der letzte Commit stammt von August 2024. Eine brechende Änderung an der Notion-API müsste jemand im Binary nachziehen, und das Installationsskript unterstützt Windows nicht.
Häufige Fragen
Um Markdown zu Notion zu bringen, und zwar in einem Rutsch. Sie halten die .md-Dateien im Repository, führen notation ship aus, und sie erscheinen als Seitenbaum in einer Notion-Seite Ihrer Wahl.
Ähnliche Inhalte
Entdecke passende Tools, Skills und Artikel zu Notation.
Alternativen zu Notation
Base Code
Base44 (Wix) · Coding · ProduktivitätBase Code ist eine geteilte Cloud-Entwicklungsumgebung von Base44. Das Team beschreibt Änderungen an einem bestehenden GitHub-Repository im Chat, prüft sie in der Vorschau und reicht sie als Pull Request ein.
Google EmbeddingGemma 2
Google DeepMind · Schreiben · Bilder · CodingGoogle EmbeddingGemma 2 ist ein offenes Modell mit 740 Millionen Parametern, das Text, Code, Bilder, Audio und Videobilder in Vektoren eines gemeinsamen 768-dimensionalen Raums umwandelt und auf Handys und Notebooks läuft.
GitGlow
GitGlow · Coding · ProduktivitätGitGlow ist ein Git-Client für den Desktop, der Ihren Code und die Änderungen Ihrer KI-Agenten in einer Review bündelt, damit Sie vor dem Ausliefern sehen, was die Maschine verlässt.