Import — und was er kostet

Basalt importiert aus Notion, Confluence, Obsidian und aus schlichten Markdown-Ordnern. Diese Seite handelt von der anderen Hälfte: was den Umzug nicht übersteht.

Es gibt sie, weil die ehrliche Antwort auf „Kann ich mein Wiki herüberholen?" nie einfach „ja" lautet. Jede Quelle enthält Dinge, für die Basalt keinen Ort hat, und jedes Exportformat hat schon einiges davon weggeworfen, bevor Basalt die Datei überhaupt sieht. Zu wissen, was das ist — vorher, nicht nachher —, ist der Unterschied zwischen einer Entscheidung und einer Überraschung.

Zwei Regeln, an die sich der Importer überall hält:

• Nichts verschwindet stillschweigend. Was verloren geht, wird im Laufbericht gezählt, mit Beispielen. Der Bericht bleibt erhalten — Einstellungen → Import zeigt vergangene Läufe.
• Ein zweiter Lauf gleicht ab, statt zu verdoppeln. Seitenkennungen werden aus dem Quellpfad abgeleitet; denselben Bereich zweimal zu importieren aktualisiert also dieselben Seiten. Was daraus folgt, steht weiter unten unter Umbenennungen.

Was aus jeder Quelle verloren geht

Wo ein Import landet

Ein Import schreibt in eine Collection, und darin wird der Baum der Quelle so nachgebildet, wie er ist:

• Ein Confluence-Bereich → eine Collection. Seine obersten Seiten werden die obersten Seiten der Collection. Dazwischen wird nichts eingezogen.
• Mehrere Bereiche in einer Verbindung bekommen je eine Seite, benannt nach dem Bereich — eine Collection kann keine zweite enthalten. Wenn Sie lieber je Bereich eine Collection hätten, legen Sie je Bereich eine Verbindung an und richten Sie jede auf ihre eigene. Sonst sind die beiden Wege gleichwertig; nur ein Link von einem Bereich in einen anderen, der nicht im selben Lauf war, bleibt Text und wird gezählt (links-unresolved).

Beachten Sie: Damit steht die Identität jeder importierten Seite fest. Kennungen werden aus der Ziel-Collection und dem Quellpfad abgeleitet. Eine Verbindung in eine andere Collection zu ziehen — oder eine Verbindung in mehrere aufzuteilen — führt also dazu, dass der nächste Lauf Seiten anlegt statt sie zu aktualisieren. Entscheiden Sie das vor dem ersten echten Import, nicht danach. Aus demselben Grund lässt sich eine importierte Seite nicht in eine andere Collection verschieben, solange ihre Verbindung existiert — siehe Importierte Seiten in eine andere Collection verschieben weiter unten.

Warum Kommentare zurückbleiben

Beide Systeme geben sie durchaus heraus: Confluence hat Fuß- und Inline-Kommentare an seiner Schnittstelle, Notion hat Seiten- und Blockkommentare. Importiert werden sie trotzdem nicht, und es liegt nicht am Lesen:

• Ein Kommentar ist von jemandem geschrieben. Er trägt einen Autor aus dem Verzeichnis des anderen Systems, und Basalt erfindet dazu keine Konten (dieselbe Regel, die „erstellt von" auf die Person setzt, die den Import ausgeführt hat). Eine Diskussion, in der jede Zeile dem Importeur zugeschrieben wird, ist schlimmer als gar keine — sie legt Menschen Worte in den Mund.
• Ein Inline-Kommentar hängt an einer Textstelle. Dieser Anker ist gegen die Auszeichnung der Quelle formuliert, und die Umwandlung nach Markdown hat sie verändert. Eine Antwort, die am falschen Satz landet, ist ein Falschzitat.
• Erledigte Stränge, Reaktionen und Erwähnungen innerhalb von Kommentaren verschärfen beide Probleme.

Was das für einen Umzug heißt: Die Diskussion bleibt in dem System, das Sie verlassen. Halten Sie das Wiki lesbar, bis die Gespräche darin niemanden mehr angehen — oder übertragen Sie die Handvoll Stränge, auf die es ankommt, von Hand in den Seitentext.

Umbenennungen und Verschiebungen

Eine Seite behält ihre Basalt-Seite über eine Umbenennung oder Verschiebung hinweg, wenn die Quelle ihr eine eigene Identität gibt — und das tun beide Verbindungen:

• Confluence — die Seitenkennung (bei einem Ordner die Ordnerkennung). Benennen Sie Runbook in Handbuch um, ziehen Sie es unter eine andere Seite: Der nächste Lauf aktualisiert die Seite, die schon hier ist.
• Notion — die 32-stellige Hex-Kennung, die Notion in jeden exportierten Datei- und Ordnernamen schreibt. Sie steckt im Export selbst, das gilt also für ein hochgeladenes ZIP genauso wie für die Verbindung über die Schnittstelle.
• Ein Markdown-Ordner oder ein Obsidian-Tresor — nichts. Es gibt keine Identität, also ist der Dateipfad die Identität, und eine umbenannte Datei kommt tatsächlich als neue Seite an. Die alte bleibt liegen, bis Sie sie löschen.

Importierte Seiten in eine andere Collection verschieben

Innerhalb ihrer Collection lässt sich eine importierte Seite bewegen wie jede andere: umbenennen, unter eine andere Seite ziehen — der nächste Lauf findet sie dort, wo Sie sie abgelegt haben.

In eine andere Collection zu verschieben, wird abgelehnt, solange die Verbindung existiert, die sie geschrieben hat; die Meldung nennt Seite und Verbindung. Der Grund ist die Identitätsregel von oben: Die Kennung wird aus der Ziel-Collection berechnet. Der nächste Lauf dieser Verbindung berechnet also dieselbe Kennung, findet die Seite — wo auch immer sie inzwischen liegt — und holt sie in die Collection zurück, in die er importiert; eine gelöschte Seite stellt er dabei wieder her. Das würde die Seite nicht unbemerkt überstehen, deshalb wird es vorher abgelehnt statt hinterher rückgängig gemacht.

Die Ablehnung gilt für den ganzen Unterbaum, nicht nur für die angeklickte Seite: Eine importierte Seite unter einer selbst angelegten Elternseite ist der Normalfall, nachdem jemand einen Wiki-Import aufgeräumt hat — und die Elternseite zu verschieben, nähme sie mit.

Zwei Wege nach vorn, je nachdem, was Sie eigentlich wollen:

• Den Import woandershin richten. Eine gespeicherte Verbindung lässt sich nicht bearbeiten — Sie löschen sie also und legen sie gegen die andere Collection neu an (oder je Bereich eine). Beachten Sie dazu „Wo ein Import landet": Der nächste Lauf behandelt dann alles als neu. Tun Sie es also vor dem ersten echten Import — oder nehmen Sie in Kauf, dass Sie eine frische Kopie beginnen.
• Die Seite loslösen. Löschen Sie die Verbindung. Die Seiten bleiben genau dort, wo sie sind, und werden zu gewöhnlichen Seiten, die sich überallhin verschieben lassen — nur erneut ausführen lässt sich dieser Import dann nicht mehr.

Seiten aus einem hochgeladenen Archiv (ZIP oder Markdown-Ordner, keine gespeicherte Verbindung) lassen sich frei verschieben: Ein Upload wird von Basalt nirgends wiederholt, es gibt also keinen Lauf, der sie zurückholen könnte. Laden Sie dasselbe Archiv von Hand erneut in dieselbe Collection, gilt derselbe Vorbehalt aber wieder.

In der Quelle gelöschte Seiten

Ein zweiter Lauf schreibt, was die Quelle noch hat. Er löscht nicht: Eine aus dem Wiki entfernte Seite bleibt in Basalt bestehen, unter der Elternseite, die sie hatte, mit dem Inhalt, den sie hatte.

Der Laufbericht benennt sie stattdessen — source-objects-vanished, mit Anzahl und Titelliste —, damit die Entscheidung bei Ihnen liegt. Automatisch in den Papierkorb wandern sie nicht: „In diesem Lauf nicht gesehen" sieht genauso aus wie eine verkürzte Bereichsliste, ein Token, das den Zugriff auf einen Bereich verloren hat, oder eine aus dem Ausschnitt herausgeschobene Seite. Und eine Seite hier in den Papierkorb zu legen nimmt alles unter ihr mit — auch Seiten, die Ihre Kolleginnen unterhalb einer importierten geschrieben haben.

Wenn sie weg sollen, löschen Sie sie in Basalt wie jede andere Seite.

Teile, die ein Token nicht lesen durfte

Ein API-Token sieht die Seiten, mit denen Sie es verbunden haben — und eine Seite darf auf Inhalte verweisen, die anderswo liegen. Verweigert die Quelle einen solchen Verweis, überspringt der Import ihn und läuft weiter: Die Seite selbst kommt an, der Laufbericht zählt unter source-objects-unreachable, was ausgelassen wurde, und benennt jeden Fall einzeln. Im Dokument bleibt ein Verweis auf den fehlenden Teil in der Quelle, damit die Lücke dort sichtbar ist, wo sie entstanden ist — nicht nur im Bericht.

Es gibt zwei Arten, und der Hinweis nennt die Blockart, damit Sie sie unterscheiden können.

Nicht für das Token freigegeben. In Notion ist das fast immer ein synchronisierter Block, dessen Original auf einer Seite liegt, die der Integration nie gegeben wurde. Sie sehen ihn im Browser, weil Sie beide Seiten sehen dürfen; das Token darf das nicht, und Notion antwortet mit object_not_found für das Original statt für die Kopie, die Sie vor sich hatten. In Confluence ist es ein Bereich oder eine Seite, die zwischen Auflisten und Abrufen verschwunden ist — oder unlesbar wurde. Diesen Fall können Sie beheben: Öffnen Sie den Verweis, den das Dokument behalten hat, geben Sie die Seite dahinter für dieselbe Integration frei und starten Sie den Import erneut. Der zweite Lauf füllt die Lücke an Ort und Stelle; nichts wird doppelt importiert.

Über die Schnittstelle überhaupt nicht verfügbar. Manches existiert nur innerhalb des Quellprodukts. Ein eingebettetes Jira-Board oder eine GitHub-Ansicht in Notion (external_object_instance_page) gehört zur Seite, die Sie ansehen, und Notion antwortet dafür mit validation_error — ganz gleich, wie es freigegeben ist. Es ist kein Inhalt, den Notion hält, sondern ein Fenster in ein anderes System. Ein erneuter Lauf ändert daran nichts; der Verweis bleibt, damit das Original an seinem Platz erreichbar bleibt.

Bis das übersprungen statt abgebrochen wurde, beendete ein einziger nicht lesbarer Block irgendwo im Arbeitsbereich den ganzen Lauf und importierte gar nichts — für ein System, in dem Teilsichtbarkeit der Normalfall ist, der falsche Handel.

Confluence

Verbunden über ein API-Token (Einstellungen → Import), nur lesend — Basalt schreibt nie in Ihr Wiki.

Links zwischen Bereichen

Confluence adressiert eine Seite über ihren Titel, und Titel sind innerhalb eines Bereichs eindeutig — nichts hindert zwei Bereiche daran, je ein „Onboarding" zu haben. Ein Link, der seinen Bereich verlässt, sagt das (ri:space-key), und Basalt trägt das mit: Ein bereichsübergreifender Link wird in dem Bereich aufgelöst, den er benennt, oder gar nicht.

Daraus folgt eine Entscheidung, die Sie einmal treffen, beim Einrichten der Verbindung — es ist dieselbe wie oben unter Wo ein Import landet:

• Alle Bereiche in einer Verbindung. Bereichsübergreifende Links landen auf der Seite im richtigen Bereich, auch wo mehrere Bereiche denselben Seitentitel verwenden. Jeder Bereich bekommt innerhalb der Collection eine eigene Seite.
• Je Bereich eine Verbindung, je Bereich eine Collection. Der sauberste Baum — die Collection ist der Bereich —, und der Preis ist, dass ein Link von einem Bereich in den anderen schlichter Text bleibt und unter links-unresolved gezählt wird. Die beiden Bereiche sind getrennte Collections, und einen internen Link dazwischen kann der Importer nicht erfinden.

Zu vermeiden ist der Fall, einer Collection, die schon einen Bereich enthält, einen zweiten hinzuzufügen: Die obersten Seiten beider stehen dann nebeneinander, und ein Seitentitel, den es in beiden gibt, löst für keinen von beiden mehr auf (siehe unten).

Ein Link wird nie durch Raten aufgelöst. Wo zwei Seiten gemeint sein könnten und nichts sagt, welche — derselbe Titel in zwei Bereichen und ein Link, der keinen benannt hat —, lässt Basalt den Text stehen und zählt ihn. Ein fehlender Link steht im Bericht und lässt sich reparieren; ein Link, der still auf die falsche Seite zeigt, ist beides nicht.

Links, die jemand als URL eingefügt hat

Nicht jeder interne Verweis in einem Wiki entstand mit dem Link-Werkzeug. Die meisten entstanden durch Kopieren der Adresse aus dem Browser — und genau die halten das alte System nach einem Umzug am Leben: Sie funktionieren ja weiter, also fällt es niemandem auf.

Basalt schreibt auch sie um. Eine eingefügte Adresse wird über die numerische Seitenkennung erkannt, die Confluence in die URL schreibt — ein vor einer Umbenennung kopierter Link findet die Seite also trotzdem — und andernfalls über die exakte Adresse. Notion funktioniert genauso, über die 32-stellige Hex-Kennung in seinen URLs (das greift auch bei einem Notion-Exportarchiv, wo gar keine lebende URL festgehalten wurde).

Vier Fälle zeigen bewusst weiter auf das alte System, weil eine Umschreibung in jedem von ihnen daneben landen könnte — und ein falscher Link ist unsichtbar, wo ein fehlender es nicht ist:

• Eine andere Instanz. Zwei Wikis verwenden dieselbe URL-Form und dieselben Seitennummern; nur der Host unterscheidet sie. Eine URL, die den Host Ihres Wikis bloß enthält (als Abfrageparameter oder als Präfix einer längeren Domain), gehört zu einer anderen Seite.
• Eine Seite, die dieser Lauf nicht importiert hat. Gezählt unter source-urls-not-rewritten — importieren Sie den benannten Bereich in dieselbe Collection und lassen Sie erneut laufen, dann repariert sich der Link selbst.
• Ein Link in einen Teil einer Seite — #eine-ueberschrift, ein fokussierter Kommentar, eine Anhangsvorschau. Ein interner Link kann diesen Teil nicht mitführen, und Sie stattdessen an den Anfang einer langen Seite zu schicken ist der falsche Ort.
• Ein Link auf eine fremde Website, deren letztes Pfadsegment zufällig einem Ihrer Seitentitel gleicht.

Anhänge, im Einzelnen

Basalt holt die Anhänge, die eine Seite tatsächlich zeigt — ein <ac:image>, ein view-file- oder viewpdf-Makro, einen Link auf eine Datei — und legt die ab, für die es einen Platz hat. Eine Seite, die eine Datei einer anderen Seite zeigt, bekommt sie von dort; die Datei wird also einmal geholt und abgelegt, und beide Seiten zeigen sie. Ein Bild kommt als Bild auf der Seite an, alles andere als benannter Link auf die Datei. Eine übersprungene Datei lässt den Text der Seite unberührt und ihren Verweis als schlichten Text stehen — und wird im Bericht gezählt.

Vier Grenzen gelten, in dieser Reihenfolge:

1. Was die Datei ist — siehe den nächsten Abschnitt. Entschieden wird nach dem Inhalt, nicht nach dem Namen.
2. Je Datei — 25 MB, oder die Dateigrößengrenze des Tarifs, falls sie niedriger liegt. Ein einzelner Anhang darüber wird gemeldet, nie abgeschnitten.
3. Der Speichertarif des Workspace. Anhänge werden geholt, solange Platz ist, und hören an der Grenze auf. Über das Limit hinaus wird nie geschrieben.
4. 400 MB je Lauf, selbst bei unbegrenztem Speicher — ein Lauf soll keine Mediathek in den Arbeitsspeicher ziehen.

Eine Obergrenze je Dateityp gibt es nicht: Ein PDF und ein PNG werden an denselben 25 MB gemessen.

Dieselben zwei Tarifgrenzen gelten für ein hochgeladenes Archiv (ein Notion-ZIP, ein Ordner voller Markdown), das sie früher umging: Eine Datei über der Dateigrenze des Tarifs wird als übersprungen gemeldet, und sobald der Workspace voll ist, bleiben die restlichen Dateien mit storage-limit-reached liegen. Die Seiten landen trotzdem — nur ihre Anhänge fehlen —, und dieselbe Quelle nach dem Aufräumen erneut zu importieren ergänzt genau diese.

Wenn mitten im Import der Speicher ausgeht: Der Import scheitert nicht. Jede Seite landet, mit Text, Struktur und jedem Anhang, der noch hineinpasste; der Rest steht unter confluence-attachments-quota. Schaffen Sie Platz oder wechseln Sie den Tarif und lassen Sie die Verbindung erneut laufen — Seiten- und Anhangskennungen sind abgeleitet, der zweite Lauf ergänzt also genau das Fehlende, statt alles ein zweites Mal zu importieren.

Diese Eigenschaft hat eine nützliche Folge: Ein Anhang hängt an der Confluence-Seitenkennung, nicht am Titelpfad der Seite. Anders als bei einer Seite (siehe Umbenennungen oben) lädt eine Umbenennung in Confluence die Anhänge also nicht neu hoch.

Was Basalt nicht ablegt

Abgelegt wird, egal auf welchem Weg es ankommt — Upload, Wiki oder Archiv:

Eingebettet gezeigt werden nur die Bilder. Alles andere wird beim Öffnen heruntergeladen — auch PDF, ein aktives Dokumentformat, das Basalt deshalb nicht in der Seite darstellt, in der Ihre Sitzung lebt.

Basalt liefert jeden Anhang von seiner eigenen Adresse aus, und eine öffentliche Freigabe liefert ihn an jeden, der den Link hat. Damit wird „welche Dateien dürfen wir behalten" zu einer Frage danach, was ein Browser mit ihnen anstellen könnte. Drei Arten werden deshalb abgelehnt — und entschieden wird nach dem Inhalt der Datei, nie nach ihrem Namen:

Zwei Folgen sollte man vor einem Umzug kennen:

• Eine Datei, deren Name lügt, wird abgelehnt. Eine HTML-Seite namens rechnung.pdf kommt nicht herein, ein SVG namens diagramm.png ebenso wenig. Dieselbe Prüfung macht die in Basalt angezeigte Art vertrauenswürdig.
• Nichts, was Sie ablegen können, wird je als Seite dargestellt. Nur Bilder werden eingebettet gezeigt, alles andere wird heruntergeladen.

Notion

Zwei Wege hinein, und sie sind nicht gleichwertig.

Über einen API-Schlüssel (Einstellungen → Import) — nur lesend, wiederholbar, und er liest Notions typisierten Blockbaum. Er weiß also, was eine Hervorhebung ist, statt zu sehen, wie sie gezeichnet wurde.

Über ein Exportarchiv (Markdown & CSV) — einmalig, ohne Zugangsdaten, und es kann nur zurückholen, was Notion in die Dateien geschrieben hat.

Warum Unterstreichung und Farbe nicht wiederkommen: Markdown, Basalts Ablagevertrag, hat für beides keine Form. Hervorhebung überlebt, weil <mark> ein echtes, semantisches HTML-Element ist, das andere Markdown-Werkzeuge darstellen. Eine Schriftfarbe wäre ein Attribut, das kein Dateiformat trägt und kein anderes Werkzeug zeigt — und die Hälfte der Paletten, die Leute in Notion wählen, ist im Dunkelmodus unlesbar.

Datenbanken und typisierte Spalten

CSV trägt keine Typen, der Importer erschließt sie also — und verweigert das Raten dort, wo Raten Daten verdürbe.

Links, die ins Leere führen, bleiben wörtlicher Text und werden im Bericht einzeln aufgeführt (links-unresolved) — ein Link aus dem importierten Unterbaum heraus ist normal, kein Fehler.

icon, title, aliases und databases sind reservierte Frontmatter-Schlüssel: Sie sagen etwas über die Seite selbst aus und werden deshalb nie zu Spalten. Eine Markdown-Datei oder Obsidian-Notiz mit icon: 📘 kommt also mit diesem Symbol an — und nicht mit einem Feld namens „icon".

Bevor Sie umziehen

1. Importieren Sie erst einen Bereich, nicht das ganze Wiki. Der Bericht sagt Ihnen, welche der Verluste oben Ihre Inhalte überhaupt betreffen.
2. Prüfen Sie danach die Rechte. Beschränkungen der Quelle werden nicht gelesen; importierte Seiten erben die der Collection.
3. Behalten Sie die Quelle, bis Sie sich das Ergebnis angesehen haben. Basalt löscht drüben nichts, und Sie sollten es auch nicht.