Markdown hält Sie zurück
(newsletter.bphogan.com)- Markdown, das häufig zum Schreiben von Entwicklerdokumentation verwendet wird, ist dank seiner Einfachheit und Zugänglichkeit beliebt, hat aber wegen seiner fehlenden strukturellen Ausdruckskraft Grenzen bei umfangreicher technischer Dokumentation
- Markdown funktioniert wie ein implizites Typsystem, sodass weder Konsistenz noch Schema-Validierung möglich sind; zudem gibt es Kompatibilitätsprobleme zwischen verschiedenen Markdown-Varianten (flavors)
- Erweiterte Syntax wie MDX erhöht zwar die Ausdruckskraft, steigert durch fehlende Portabilität und Standardisierung zwischen Systemen jedoch eher die Komplexität
- reStructuredText, AsciiDoc, DocBook und DITA bieten explizite Strukturen und semantisches Markup, was Wiederverwendbarkeit und maschinelle Interpretierbarkeit verbessert
- Für kleine Dokumente reicht Markdown aus, doch für die Verwaltung großer, kanalübergreifender Dokumentationen ist ein Wechsel zu strukturierten Formaten nötig
Die strukturellen Grenzen von Markdown
- Markdown kann mit einer einfachen, menschenlesbaren Syntax ansehnliche Dokumente für GitHub oder statische Websites erzeugen
- Es beschreibt jedoch nicht die Bedeutung der Inhalte und bietet daher zu wenig Strukturinformationen, die Maschinen verstehen können
- Suchmaschinen, LLMs, IDEs und KI-Agenten nutzen die semantische Struktur von Dokumenten, Markdown erzeugt jedoch nur begrenzte HTML-Tags
- Wegen plattformspezifischer Syntaxunterschiede in Markdown entstehen bei Wiederverwendung oder Inhaltsintegration Inkonsistenzen
- Letztlich ist Markdown ein Format auf dem Niveau des kleinsten gemeinsamen Nenners und daher für komplexes Dokumentationsmanagement ungeeignet
Das Problem des impliziten Typsystems in Markdown
- Markdown ist ein Format ohne explizites Schema oder Typdefinitionen, sodass dieselbe Überschrift oder Liste je nach Kontext eine andere Bedeutung haben kann
- Es gibt zahlreiche Markdown-Varianten (flavors), wodurch Unterschiede beim Rendering zwischen Tools entstehen
- Beispiel: Manche Tools unterstützen Fußnoten, andere ignorieren sie
- MDX erweitert die Ausdruckskraft durch eingebettete React-Komponenten, ist aber wegen Kompatibilitätsproblemen zwischen Systemen wenig portabel
- Solche Erweiterungen sollen die Grenzen von Markdown ausgleichen, sind jedoch nur nicht standardisierte Behelfslösungen
Warum semantisches Markup wichtig ist
- Semantisches Markup beschreibt die Bedeutung statt der Form von Inhalten
- Beispiel: „Schritt“ (
step) und „Listenelement“ können visuell gleich aussehen, bedeuten aber nicht dasselbe
- Beispiel: „Schritt“ (
- HTML5 hat mit bedeutungsbasierten Tags wie
<section>,<article>,<aside>die strukturelle Ausdruckskraft gestärkt - Zentrale Vorteile semantischen Markups
- Transformation und Wiederverwendung: Dieselben Inhalte lassen sich in HTML, PDF, ePub und andere Formate umwandeln
- Maschinelle Interpretierbarkeit: LLMs und Agenten erkennen die Struktur klarer und liefern präzisere Antworten
- Markdown liefert diese Strukturinformationen nicht, wodurch bei Nachbearbeitung oder Konvertierung Informationsverluste entstehen
Vergleich alternativer Formate
- reStructuredText
- Ein im Python-Ökosystem mit Sphinx verwendetes Format, das über Direktiven (directives) und Rollen (roles) strukturelle Bedeutung ausdrückt
- Unterstützt explizite Strukturelemente wie Code-Blöcke, Hinweise (
note) und Querverweise (:ref:) - Für umfangreiche technische Dokumentation geeignet und unterstützt die Erzeugung von HTML und PDF
- AsciiDoc
- Ein semantisches Textformat mit Attributen (attributes), bedingten Inhalten und Include-Funktionen
- Unterstützt für technische Dokumentation spezialisierte Ausdrucksformen wie Hinweise vom Typ
NOTEundWARNING, UI-Elemente und Tastenkürzel - Kann über AsciiDoctor in HTML, PDF, ePub, DocBook und weitere Formate konvertiert werden
- DocBook (XML)
- Ein XML-basiertes Modell für technisches Publizieren, das ein System bedeutungsvoller Tags wie
<command>,<note>,<xref>bereitstellt - Enthält Tags für Glossare, Indizes, UI-Elemente, Funktionsnamen und andere Bestandteile professioneller Dokumentation
- Über XSLT-Stylesheets in verschiedene Ausgabeformate konvertierbar
- Besonders vorteilhaft für Validierung großer Dokumentstrukturen und Indexerstellung
- Ein XML-basiertes Modell für technisches Publizieren, das ein System bedeutungsvoller Tags wie
- DITA (Darwin Information Typing Architecture)
- Eine modulare XML-basierte Struktur, die als Standard für technische Unternehmensdokumentation verwendet wird
- Eine topic-basierte XML-Architektur, die prozedurale Strukturen wie
<task>,<step>klar definiert - Wird als Standard für Dokumentationsmanagement in Unternehmen für Content-Reuse (
conref), Filterung und kanalübergreifendes Publishing eingesetzt - Unterstützt über das DITA Open Toolkit die Automatisierung von Rendering und Konvertierung
Warum XML notwendig ist, auch wenn es unbequem wirkt
- Markdown ist leichtgewichtig, aber eine Behelfslösung ohne Struktur, Standardisierung und Konsistenz
- Wenn Sie Markdown bereits mit MDX, Plugins und benutzerdefinierten Skripten komplexer machen,
ist die direkte Einführung eines strukturierten Formats langfristig stabiler
Was also tun?
- Für kleine Dokumente wie READMEs oder einmalige Unterlagen reicht Markdown aus,
für umfangreiche, wiederverwendbare und kanalübergreifende Dokumentation sind reStructuredText, AsciiDoc, DocBook und DITA besser geeignet - Wenn Konzeptdokumente, Entwicklerdokumentation, Wiederverwendung oder groß angelegte Verwaltung nötig sind, sollte man in der Reihenfolge reST/AsciiDoc → DocBook/DITA prüfen
- Sinnvoll ist ein Ansatz, bei dem das strukturell reichhaltigste Format als Quelle verwendet und bei Bedarf in Markdown konvertiert wird
- Markdown ist als Ausgabeformat nützlich, als Quelle der Wahrheit (source of truth) erschwert es jedoch strukturelle Erweiterungen
- Optimal ist es, die Quelle in einem Format mit reichhaltiger semantischer Struktur zu halten und Markdown für nachgelagerte Ausgabezwecke zu verwenden
7 Kommentare
Ist rst ein XML-basiertes Format? Davon höre ich zum ersten Mal. Die Zusammenfassung ist seltsam.
Offenbar wurde der Titel so formuliert, weil in der Zusammenfassung bei der Erörterung der Auswahlkriterien verschiedene XML-Formate zusammengefasst wurden.
Ich habe ihn entsprechend dem Original korrigiert.
Wenn nötig, kann man in Markdown HTML verwenden und dort Mermaid anhängen, dann klappt es so halbwegs … aber darüber hinaus wirkt es, als würde es zu Arbeit an Dokumenten um der Dokumentationsarbeit willen werden.
Menschen kommen vor KI. Stehl nicht, was ich geschrieben habe. Dieses Gerede von Semantik ist doch lächerlich.
Wenn man eine spezielle Syntax verwenden muss, entsteht wieder eine weitere Lernkurve, und dedizierte Parsing-Tools, Viewer, Editoren usw. müssten alle reibungslos unterstützt werden. In dem Maßstab wäre es vielleicht besser, einfach Google Docs oder Notion zu nutzen, die sich mit den meisten AI-Diensten problemlos verbinden lassen.
Hacker-News-Kommentare
Der Kern von Markdown ist die breite Unterstützung, die anderen Sprachen fehlt Die meisten Alternativen brauchen separate Tools und lassen sich in Umgebungen, die Markdown bereits unterstützen, nicht verwenden Sogar Google Docs unterstützt das Einfügen von Markdown als versteckte Funktion Auch wenn es nicht perfekt ist, ist der Vorteil, dass man es „überall verwenden kann“ So wie HTML einfacher als SGML war, aber durch Browser-Unterstützung zum Standard wurde, kann sich auch Markdown mit der Zeit weiterentwickeln Die Unklarheit der Standardisierung, fehlende Funktionen und Kompatibilitätsprobleme ähneln der Situation zu HTML4-Zeiten Statt eines vollständigen Ersatzes scheint schrittweise Evolution der realistischere Weg zu sein
Markdown kann überall HTML-Tags enthalten Das wird auch in der offiziellen Dokumentation ausdrücklich erwähnt Daher existiert die vom Autor genannte Einschränkung in der Praxis nicht
oderschreiben muss, gibt es keinen Grund mehr, Markdown zu verwenden Wenn die Antwort letztlich „Dann nutze eben HTML“ lautet, verschwindet damit der Daseinsgrund von MarkdownWährend meines Physikstudiums an der Universität habe ich Arbeiten in LaTeX geschrieben In der Chemie wurde Word verwendet, Standards unterscheiden sich also je nach Fachgebiet Die Versionsnummern von TeX drücken den angestrebten Fertigstellungsgrad als Annäherung an π aus Die aktuelle Version ist 3.141592653 und wurde über 47 Jahre stabil gehalten Siehe TeX-Wiki, Erklärung zu Pi-Versionen Für CLI-Tools ist auch das manpage-Format nützlich
Markdown ist so etwas wie ein Minimum Viable Product (MVP) Es ist leicht zu lernen und bleibt auch ohne Rendering gut lesbar Für die PDF-Erstellung bin ich von AsciiDoc zu Typst gewechselt, weil damit Zugänglichkeitsprobleme gelöst werden Aber keine Markup-Sprache verbessert automatisch die Qualität des Schreibens Nur weil man den Stift wechselt, wird der Text nicht besser
Der Tenor dieses Textes ist die Behauptung, Markdown bremse die Entwicklung von LLMs Aber die Annahme, semantischen Reichtum automatisch gewinnen zu können, ist unrealistisch Im Team hat ohnehin niemand Zeit für solche Arbeit, und Markdown reicht völlig aus Wie bei Diskussionen zum Semantic Web ist am Ende entscheidend, wer die Daten pflegt
Ich schreibe meinen Blog mit Org-mode + Emacs Besonders gefällt mir die Funktion, Code-Blöcke zu verknüpfen und direkt im Dokument auszuführen Ich habe auch Plattformen wie Blorgit und lazyblorg ausprobiert, aber die Einrichtung war mühsam, deshalb exportiere ich direkt nach HTML und lade es per rsync auf den Server Mit einem Ruby-Skript ergänze ich einen Index und veröffentliche es Es ist viel ausdrucksstärker und natürlicher als Markdown
Ich stimme der Aussage „Markdown hat zu wenig Struktur“ teilweise zu, aber der binäre Ansatz stört mich Man hätte zuerst verstehen sollen, welche Struktur überhaupt benötigt wird, bevor man ein Format auswählt Deshalb wirkt es auf mich etwas unerquicklich und schwer, voll zuzustimmen
DITA als Markdown-Alternative vorzuschlagen, ist völlig am Thema vorbei DITA ist ein XML-System für große Unternehmen und verfolgt einen ganz anderen Zweck als Markdown Es ist nur in Umgebungen mit mehr als 5.000 Mitarbeitern oder mehrsprachigen Produktlinien sinnvoll Wenn man in einer Situation ist, in der man Markdown verwendet, passt DITA überhaupt nicht Beides ist Zeitverschwendung
Ich benutze Markdown seit über 10 Jahren, und es funktioniert immer noch gut Die Aussagen des Artikels sind auch nicht völlig falsch, aber es sind nicht die Probleme, die Markdown-Nutzer tatsächlich spüren Wenn nötig, kann man eben etwas anderes verwenden Trotzdem war der Titel gut genug, dass ich etwa 5 Minuten lang gelesen habe
Es ist merkwürdig, MyST als eine Form von Markdown zu erwähnen und dann wieder reStructuredText (rST) als Beispiel anzuführen Der Zweck von MyST ist gerade, ein Ersatz für rST zu sein Die Syntax wirkt wie Markdown, unterstützt aber zugleich strukturelle Semantik sowie Directives und Roles Auch im Sphinx-Issue gibt es dazu entsprechende Diskussionen
In letzter Zeit sieht man viele Beiträge dieser Art.
Textdateien, Markdown, stärker strukturierte Formate
Wenn man darauf umstellt, gibt es nicht die eine richtige Antwort; man sollte einfach zur passenden Zeit das passende Format verwenden.
Und wenn man immer versucht, alles in einer einzigen Datei unterzubringen, entstehen zwangsläufig Probleme. Deshalb ist es unvermeidlich, nach Themen zu ordnen und systematisch zu strukturieren.