Jupyter Notebook in Markdown umwandeln — kostenlos und privat

Machen Sie aus einem .ipynb-Notebook sauberes Markdown, direkt im Browser. Behält Text und Code, entfernt die Base64-Bilder und Ausführungs-Metadaten, die das rohe JSON aufblähen.

Jupyter Notebook in Markdown: das Erzählte behalten, die Verpackung wegwerfen

Ein Notebook sind zwei Dokumente unter einem Dateinamen. Da ist das, was Sie geschrieben haben — Überschriften, Erklärungen, Code, das ausgegebene Ergebnis, auf das es ankam — und da ist die JSON-Hülle, in der das Format es ablegt. Öffnen Sie eine .ipynb in einem Texteditor und Sie sehen die Hülle: jede Zeile Prosa in einer eigenen Zeichenkette, "execution_count": 7 an jeder Zelle, überall leere "metadata": {}-Objekte, und irgendwo mittendrin ein viertel Megabyte Base64, das sich als ein kleines Streudiagramm entpuppt.

Die Umwandlung nach Markdown wirft die Hülle weg und behält das Dokument. Ihre Markdown-Zellen waren bereits Markdown, sie gehen unverändert durch. Code-Zellen werden zu eingezäunten Blöcken mit der Sprache des Kernels als Kennzeichnung — die Form, die jedes Modell, jede README und jeder Static-Site-Generator ohnehin versteht. Legen Sie oben eine .ipynb ab: die Umwandlung geschieht in diesem Browser-Tab, die Datei wird nie hochgeladen.

Wo das Gewicht tatsächlich sitzt

Man nimmt an, ein großes Notebook sei wegen des Codes groß. Das ist es so gut wie nie. Das Gewicht sitzt an vier Stellen, absteigend sortiert:

  • Base64-Bildausgaben. Jedes plt.show() schreibt das gerenderte PNG als Base64-Text in die Datei. Eine Abbildung sind üblicherweise 200 bis 400 KB an Zeichen. Ein Notebook mit einem Dutzend Diagrammen besteht überwiegend aus Diagrammen. Für jemanden, der den Text liest, bedeutet nichts davon irgendetwas.
  • HTML-Darstellungen von Dataframes. Pandas gibt für dasselbe Ergebnis sowohl text/plain als auch text/html aus. Die HTML-Fassung schleppt Inline-Styles und eine <table> mit einem Tag pro Zelle mit sich; sie kann das Zwanzigfache der Klartextfassung wiegen und sagt dabei genau dasselbe.
  • Einzelbilder von Fortschrittsbalken. Eine tqdm-Schleife schreibt bei jeder Aktualisierung eine neue Zeile, getrennt durch Wagenrückläufe. Am Ende steht in der Datei hundertfach ein Balken, der nur ein einziges Mal angezeigt wurde.
  • Metadaten je Zelle. Einzeln belanglos, in Summe nicht: Zell-IDs, Ausführungszähler, Einklapp-Kennzeichen und leere Metadaten-Objekte summieren sich über einige hundert Zellen.

Die Umwandlung oben behandelt jeden dieser Fälle. Medien-Nutzdaten werden gezählt und durch eine einzelne Platzhalterzeile ersetzt, damit noch erkennbar bleibt, wo eine Abbildung stand. Bietet ein Ergebnis sowohl Klartext als auch HTML, gewinnt der Klartext. Wagenrücklauf-Folgen werden auf den Endzustand der Zeile eingedampft. Metadaten entfallen vollständig. Das Werkzeug meldet, was es entfernt hat: die Ersparnis ist sichtbar, nicht bloß behauptet.

Warum eingezäunte Blöcke mehr zählen, als sie aussehen

Das Nützlichste, was Markdown einem Notebook antut, ist die ausdrückliche Markierung der Grenze zwischen Prosa und Code. Im rohen JSON existiert diese Grenze nur als ein "cell_type"-Feld einige Zeilen oberhalb des Inhalts. Achtlos plattgedrückt laufen eine Erklärung und der zugehörige Code ineinander, und wer liest — Mensch wie Modell — muss allein aus der Syntax erschließen, was was ist.

Ein mit der Sprache gekennzeichneter Zaun nimmt das Raten heraus. Er trägt außerdem die Kernel-Sprache weiter: der Konverter liest language_info aus den Notebook-Metadaten, ersatzweise die kernelspec, sodass ein R- oder Julia-Notebook als R oder Julia gekennzeichnet wird statt stillschweigend als Python. Ausgaben erhalten ihren eigenen, ungekennzeichneten Zaun unter der Zelle, die sie erzeugt hat, eingeleitet von einer schlichten Zeile Output:. Das hält den Ursache-Wirkungs-Zusammenhang sichtbar, ohne eine Syntax zu erfinden, die Markdown nicht hat.

Tracebacks lohnt es sich zu behalten

Es liegt nahe, Fehlerausgaben mit allem anderen zu entfernen. Meist ist das die falsche Entscheidung. Wenn Sie einem Modell ein Notebook geben und fragen, warum eine Zelle scheitert, ist der Traceback die ganze Frage. Unangenehm an Tracebacks im Rohzustand ist nicht der Inhalt, sondern die ANSI-Farbcodes, in die IPython sie einwickelt — Escape-Sequenzen, die im Terminal als lesbare Farbe erscheinen und überall sonst als ESC[0;31m-Kauderwelsch.

Diese Sequenzen werden entfernt und der Traceback-Text bleibt. Lange werden aus der Mitte heraus gekürzt statt vom Ende her, denn in einem tiefen Stack sind die nützlichen Frames die ersten und die letzten, und die zweihundert Zeilen Bibliotheks-Innenleben dazwischen sind genau das, was Sie ohnehin übersprungen hätten.

Notebooks in einem Repository-Auszug

Dieselbe Umwandlung läuft in den GitHub-, GitLab- und Ordner-Werkzeugen dieser Seite. Wählen Sie in einem Repository eine .ipynb aus, landet sie als lesbare Zellen in der Ausgabe statt als Wand aus JSON. Das zählt mehr, als es klingt: in einem Data-Science-Repository steckt die eigentliche Argumentation häufig in den Notebooks — und bisher waren das die Dateien, die man abwählen musste, um die Ausgabe brauchbar zu halten.

In diesem Zusammenhang ist die Ausgabegrenze enger als auf dieser Seite, denn ein Repository-Auszug ist Kontext für ein Modell, und Zellausgaben sind daran der je Token unrentabelste Teil. Ein Hinweis im umgewandelten Text hält fest, wie viel entfernt wurde: nichts verschwindet stillschweigend.

Ältere Notebooks funktionieren weiterhin

Format-Version 4 legt Zellen in einem cells-Array auf oberster Ebene ab. Version 3, die in öffentlichen Repositories aus den frühen 2010ern noch verstreut herumliegt, verschachtelt sie eine Ebene tiefer in worksheets und nennt das Quellfeld input statt source. Beide Formen werden gelesen, ebenso der Ausgabetyp pyout aus Version 3, wo Version 4 execute_result sagt.

Zweierlei wird bewusst nicht versucht. Notebook-Widgets — interaktive Regler und Diagramme auf Basis von ipywidgets — legen ihren Zustand in einem eigenen Metadaten-Block ab und ergeben als Text nichts Brauchbares; der Platzhalter sagt Ihnen, dass eines da war. Und die Ausführungsreihenfolge der Zellen bleibt so, wie sie in der Datei steht, ohne Sortierung nach Ausführungszähler: die Reihenfolge, in der man ein Notebook liest, ist die, in der es geschrieben ist.

Nichts wird hochgeladen

Notebooks tragen Dinge mit sich, die man vergisst: ein API-Schlüssel, beim Debuggen in eine Zelle geklebt, ein Datenbank-Verbindungsstring, ein Ausschnitt Produktivdaten, ausgegeben zur Kontrolle eines Joins. Die Umwandlung läuft als JavaScript in diesem Tab. Es gibt keinen Upload-Schritt, keine Kopie auf einem Server und nichts, dessen Löschung man hinterher erbitten müsste. Tab zu, und es ist weg.

Wenn Sie Klartext statt Markdown möchten — keine Zäune, keine Struktur, nur Prosa und Code — leistet das der Konverter von Notebook zu Text, und die von Ihnen gewählte Datei kommt mit.