CSV in Markdown-Tabelle: So konvertieren Sie eine CSV für GitHub, READMEs und Dokumentation
Machen Sie aus einer CSV eine Markdown-Tabelle für GitHub, ein README oder Doku: Ausrichtung pro Spalte, sichere Pipes und Zeilenumbrüche, Größengrenzen.
Aktualisiert am 8. November 20269 Min. Lesezeit
Um eine CSV in eine Markdown-Tabelle umzuwandeln, ziehen Sie die Datei in einen CSV-zu-Markdown-Konverter, prüfen die gerenderte Vorschau, legen die Ausrichtung jeder Spalte fest und kopieren das Ergebnis in Ihr README, Ihr Issue oder Ihre Dokumentationsseite. Der Konverter schreibt die drei Teile, die jede Markdown-Tabelle braucht: eine Kopfzeile, eine Trennzeile aus Bindestrichen und eine Zeile pro Datensatz. Schwierig ist nicht die Form, sondern der Inhalt der Zellen: Ein senkrechter Strich, ein Zeilenumbruch in einem Feld in Anführungszeichen oder ein einzelnes Sternchen kann eine Zeile zerteilen, Daten in die falsche Spalte schieben oder Text kursiv setzen. Dieser Leitfaden behandelt die Schritte, die Ausrichtung, diese Problemzeichen und die Größengrenzen, die vor dem Einfügen zählen.
So konvertieren Sie eine CSV in eine Markdown-Tabelle
CSV hinzufügen
Öffnen Sie den CSV-zu-Markdown-Konverter und ziehen Sie eine .csv-, .tsv-, .txt- oder .psv-Datei hinein. Trennzeichen, Anführungszeichen und Kodierung werden aus der Datei selbst erkannt, und das Werkzeug zeigt an, wofür es sich entschieden hat.
Kopfzeile prüfen
Lassen Sie Erste Zeile als Kopfzeile eingeschaltet, wenn Zeile eins die Spaltennamen enthält. Schalten Sie es aus, wenn die Datei direkt mit Daten beginnt; die Tabelle erhält dann automatisch die Beschriftungen Col 1, Col 2.
Ausrichtung festlegen
Wählen Sie eine Standard-Ausrichtung für die ganze Tabelle und ändern Sie dann einzelne Spalten über das Auswahlmenü in ihrem Vorschau-Kopf. Zahlen lesen sich meist rechtsbündig am besten.
Vorschau in beiden Ansichten prüfen
Wechseln Sie zwischen Gerendert und Markdown. Die gerenderte Ansicht zeigt, ob sich eine Zelle mit Sternchen oder Zeilenumbruch richtig verhält; die Rohansicht zeigt genau das, was Sie einfügen werden.
Kopieren oder herunterladen
Klicken Sie auf In Markdown konvertieren, dann auf Markdown kopieren für ein README oder einen Pull Request, oder auf .md herunterladen mit dem Dateinamen, den Sie unter Herunterladen als eingetragen haben.
Woraus eine Markdown-Tabelle besteht
Eine Markdown-Tabelle im Dialekt GitHub-Flavored Markdown ist reiner Text. Die erste Zeile ist die Kopfzeile, die Zellen sind durch senkrechte Striche (Pipes) getrennt. Die zweite Zeile ist die Trennzeile: Bindestriche unter jeder Spalte, und erst ihr Vorhandensein macht den Block überhaupt zu einer Tabelle. Jede weitere Zeile ist ein Datensatz. GitHub, GitLab, Obsidian, VS Code und die meisten Generatoren für statische Websites lesen genau dieses Format, eine konvertierte Tabelle funktioniert also überall.
Das Format hat feste Grenzen, die Sie vorher kennen sollten. Zellen lassen sich nicht über Zeilen oder Spalten verbinden, jede Tabellenzeile muss in einer einzigen Textzeile stehen, und die Kopfzeile wird immer fett dargestellt. Hat eine CSV-Zeile weniger Zellen als die Kopfzeile, füllt der Konverter sie mit leeren Zellen auf; hat sie mehr, wird die Tabelle auf die breiteste Zeile erweitert, damit nichts stillschweigend abgeschnitten wird.
Spaltenausrichtung in einer Markdown-Tabelle
Die Ausrichtung steht ausschließlich in der Trennzeile, als Doppelpunkte neben den Bindestrichen. Der Konverter schreibt sie für Sie, und zwar auf Wunsch für jede Spalte anders:
| Ausrichtung | Geschriebene Trennzeile | Geeignet für |
|---|---|---|
| Links | :--- | Namen, Bezeichnungen, Freitext |
| Mittig | :---: | Kurze Statusspalten, Ja/Nein, einzelne Zeichen |
| Rechts | ---: | Preise, Stückzahlen, Prozentwerte |
| Keine | --- | Dem Renderer überlassen (fast überall linksbündig) |
Der typische Fall ist eine Tabelle, die einen Produktnamen mit einem Preis und einem Lagerbestand mischt: Stellen Sie die Standardausrichtung auf Links und schalten Sie die beiden Zahlenspalten in ihrem Vorschau-Kopf auf Rechts. Rechtsbündige Zahlen stehen mit ihrer letzten Ziffer untereinander, und genau das macht eine Zahlenspalte auf einen Blick vergleichbar. Beachten Sie, dass manche Anwendungen die Doppelpunkte ignorieren; Notion zum Beispiel macht aus einer eingefügten Markdown-Tabelle eine eigene Tabelle und verwirft die Ausrichtung.
Ausrichtung pro Spalte, sicheres Maskieren von Pipes und Zeilenumbrüchen, aufgefüllte oder kompakte Ausgabe, Kopieren oder .md-Download. Kostenlos: eine CSV bis 25 MB, ohne Zeilenlimit, mit allen Formatierungsoptionen. Pro: bis zu 50 Dateien auf einmal als ZIP oder als ein zusammengeführtes Dokument. Alles läuft auf Ihrem Gerät, nicht auf unseren Servern.
CSV in Markdown konvertierenPipes, Zeilenumbrüche und Zeichen, die eine Tabelle zerstören
Text aus einer Tabellenkalkulation weiß nicht, dass er gleich zu Markdown wird. Das sind die Zeichen, die Ärger machen, und so geht der Konverter mit jedem um:
| In einer Zelle | Was ohne Maskierung schiefgeht | Was der Konverter tut |
|---|---|---|
| Ein senkrechter Strich | | Er beendet die Zelle zu früh; die Zeile erhält eine Spalte mehr, die Daten verrutschen | Wird immer als \| maskiert |
| Ein Backslash | Er kann das folgende Zeichen verschlucken | Wird immer verdoppelt, ein Windows-Pfad bleibt also erhalten |
| Ein Zeilenumbruch in einem Feld in Anführungszeichen | Die Zeile endet mitten in der Zelle, und der Rest der Tabelle fällt auseinander | Wird standardmäßig zu <br>, alternativ zu einem wörtlichen \n oder einem Leerzeichen |
| Sternchen, Unterstriche, Backticks | Text wird fett, kursiv oder zu Code | Nur maskiert, wenn Markdown-Zeichen maskieren eingeschaltet ist |
| Eckige Klammern, spitze Klammern, Tilden | Können zu Links, HTML oder Durchstreichung werden | Mit demselben Schalter maskiert |
| Bindestriche, Punkte, Pluszeichen | Nichts, innerhalb einer Tabellenzelle | Bleiben unverändert, damit Datumsangaben und Preise lesbar bleiben |
Die Einstellung für Umbrüche heißt Zeilenumbrüche in einer Zelle. Behalten Sie <br> für GitHub und GitLab bei: Dort wird es als echter Umbruch dargestellt, und eine Postanschrift bleibt eine einzige lesbare Zelle. Wählen Sie Wörtliches \n, wenn die Tabelle an einen Ort geht, der HTML entfernt, und Sie trotzdem sehen möchten, dass dort ein Umbruch war. Wählen Sie Leerzeichen, wenn die Umbrüche nur ein Zufallsprodukt des Exports sind, etwa umbrochener Text in einer Tabellenspalte.
Lassen Sie Markdown-Zeichen maskieren ausgeschaltet, solange die Vorschau kein Problem zeigt. Die meisten Tabellen enthalten keines dieser Zeichen, und bei eingeschaltetem Schalter bekommt jedes davon einen sichtbaren Backslash in der Rohdatei. Eine Zelle mit einem Wert wie _entwurf_ oder einem Wort zwischen Sternchen ist genau der Fall, in dem Sie ihn brauchen: Ohne Maskierung erscheint sie kursiv, und die Zeichen verschwinden.
Zuerst die CSV richtig einlesen
Viele kaputte Tabellen sind schon kaputt, bevor eine einzige Zeile Markdown geschrieben wird, weil die CSV am falschen Zeichen getrennt wurde. Der Konverter testet Komma, Semikolon, Tabulator und Pipe an einer Stichprobe, behält das Zeichen mit den gleichmäßigsten Zeilenbreiten und weist Sie darauf hin, wenn das Ergebnis unsicher wirkt. Exporte aus deutschsprachigen Excel-Versionen verwenden meist Semikolons; zeigt die Vorschau alles in einer Spalte, stellen Sie das Trennzeichen von Hand ein.
- Kodierung: Erscheinen Umlaute als Zeichensalat, ist die Datei wahrscheinlich Windows-1252 und nicht UTF-8. Stellen Sie sie von Hand ein; eine Datei mit Byte-Order-Mark (BOM) hat immer Vorrang, und die unsichtbare Markierung, die Excels Export „CSV UTF-8“ hinzufügt, wird entfernt, damit sie nicht an Ihrer ersten Spaltenüberschrift hängt.
- Führende Zeilen überspringen: Berichtsexporte haben oft einen Titel und ein Datum über der eigentlichen Kopfzeile. Überspringen Sie diese, damit Zeile eins zur Kopfzeile wird.
- Leere Zeilen entfernen und Leere Spalten entfernen: Exporte aus Tabellenkalkulationen sammeln unten leere Zeilen und seitlich ungenutzte Spalten. Jede davon würde zu leeren Zellen in Ihrer Tabelle.
- Zeilen begrenzen: Ein README braucht die ersten 20 Zeilen eines großen Exports, nicht alle. 0 behält alle Zeilen.
Braucht die Tabelle weniger Spalten als die CSV, entfernen Sie diese vorher mit CSV-Spalten hinzufügen oder entfernen; Einzelheiten finden Sie unter Spalten aus einer CSV entfernen. Eine Tabelle mit vier gezielt gewählten Spalten liest sich weit besser als eine mit zwölf.
Größengrenzen: der Konverter und der Ort, an dem Sie einfügen
In der kostenlosen Version nimmt der Konverter eine Datei bis 25 MB an, ohne Begrenzung der Zeilenzahl. Laut Messung der Website wird ein 25-MB-Export mit etwa 225.000 Zeilen auf einem Desktop-Rechner in rund einer Sekunde konvertiert. Die Vorschau zeigt nur die ersten Zeilen und Spalten, damit die Seite flüssig bleibt, der Download und der kopierte Text enthalten aber alle. Pro konvertiert bis zu 50 Dateien auf einmal, entweder als ein ZIP oder zusammengeführt in ein einziges Markdown-Dokument, in dem jede Tabelle unter einer Überschrift aus ihrem Dateinamen steht.
Die engere Grenze setzt meist das Ziel, nicht der Konverter:
| Ziel | Praktische Grenze | Was zu tun ist |
|---|---|---|
| GitHub-Issue, Pull Request oder Kommentar | Der Text ist auf 65.536 Zeichen begrenzt | Zeilen begrenzen nutzen oder die Tabelle als .md-Datei einchecken |
| README oder Doku-Datei in einem Repository | Keine knappe Obergrenze, aber eine sehr lange Tabelle ist schwer lesbar | Einen Ausschnitt zeigen und die vollständige CSV verlinken |
| Jede Seite, die auf dem Handy gelesen wird | Breite Tabellen scrollen seitlich | Bei etwa 4 bis 6 Spalten bleiben |
| Rohtext in einem Editor | Auffüllen macht jede Zeile so breit wie den breitesten Wert | Bei langen Textzellen die kompakte Ausgabe verwenden |
Denken Sie daran, dass Markdown größer ist als die CSV, aus der es stammt: Jede Zelle bekommt Striche und Leerzeichen, und das Auffüllen fügt noch mehr hinzu. Ein vollständiger Export gehört selten in ein Dokument. Zwanzig gut gewählte Zeilen mit einem Link zur Quelldatei sind das, was die meisten Leser wollen.
Weitere nützliche Optionen
- Zeilen nummerieren fügt eine Zählspalte hinzu, praktisch, wenn Prüfer in einem Kommentar „Zeile 14 ist falsch“ schreiben müssen.
- Erste Datenzeile fett und Erste Spalte fett gelten nur für den Tabellenkörper, weil die Kopfzeile beim Rendern ohnehin fett ist.
- Anführungszeichen lässt sich auf doppeltes Anführungszeichen, Apostroph oder keines stellen; ein Anführungszeichen öffnet ein Feld nur ganz am Anfang, daher bleibt der Apostroph in O'Brien normaler Text.
Wann eine Markdown-Tabelle die falsche Wahl ist
Markdown-Tabellen sind für kleine, lesbare Daten innerhalb eines Textes gedacht. Muss jemand sortieren, filtern oder rechnen, geben Sie die Daten als Tabelle mit CSV in Excel weiter. Liest ein Programm die Daten, ist CSV in JSON das bessere Format. Möchten Sie eine große Datei nur durchsehen, bevor Sie Zeilen auswählen, öffnen Sie sie zuerst im CSV-Viewer.
Steht Ihre Tabelle in einem Word-Dokument statt in einer CSV, ist die Aufgabe eine andere: Überschriften, Listen und Formatierung kommen mit. Das behandelt der Leitfaden Word in Markdown konvertieren, mit dem Werkzeug Word in Markdown.
Häufige Fragen
Wie konvertiere ich eine CSV in eine Markdown-Tabelle?
Ziehen Sie die CSV in den CSV-zu-Markdown-Konverter, lassen Sie Erste Zeile als Kopfzeile eingeschaltet, wenn Zeile eins die Spaltennamen enthält, legen Sie die Ausrichtung fest, klicken Sie auf In Markdown konvertieren und kopieren Sie das Ergebnis oder laden Sie es als .md-Datei herunter. Kopfzeile, Trennzeile und Maskierung werden für Sie geschrieben.
Wie richte ich eine Spalte in einer Markdown-Tabelle rechtsbündig aus?
Setzen Sie einen Doppelpunkt an das rechte Ende der Trennzeile dieser Spalte, also ---:. Im Konverter stellen Sie das über das Auswahlmenü im Vorschau-Kopf der Spalte ein, sodass Zahlenspalten rechtsbündig sein können, während Text links bleibt.
Wie setze ich einen senkrechten Strich in eine Zelle einer Markdown-Tabelle?
Maskieren Sie ihn als \|, damit er nicht als Zellenende gelesen wird. Der Konverter tut das automatisch bei jedem senkrechten Strich, auch innerhalb von Text, der wie Code aussieht.
Kann eine Zelle einer Markdown-Tabelle einen Zeilenumbruch enthalten?
Nicht direkt: Jede Tabellenzeile muss eine einzige Textzeile sein. Auf GitHub und GitLab wird ein <br> in der Zelle als Zeilenumbruch dargestellt, und das ist die Voreinstellung des Konverters für mehrzeilige CSV-Felder. Sie können stattdessen auch ein wörtliches \n oder ein einfaches Leerzeichen wählen.
Warum erscheint meine ganze CSV in einer einzigen Spalte?
Die Datei verwendet ein anderes Trennzeichen als das angewendete, meist ein Semikolon bei Exporten aus europäischen Excel-Versionen. Stellen Sie das Trennzeichen von Hand auf Semikolon, Tabulator oder Pipe, dann trennen sich die Spalten.
Gibt es eine Größengrenze für die Umwandlung von CSV in Markdown?
Die kostenlose Version konvertiert eine Datei bis 25 MB ohne Zeilenlimit und mit allen Formatierungsoptionen. Pro verarbeitet bis zu 50 Dateien auf einmal. Häufiger setzt das Ziel die Grenze: GitHub begrenzt den Text eines Issues oder Pull Requests auf 65.536 Zeichen, nutzen Sie dort also Zeilen begrenzen.