Skip to content

Markdown: HTML aus Text erzeugen

Der erste längere (Erläuterungs-)Text, den ich zur Veröffentlichung im Netz verfasst habe, war im September 1998 die Header-FAQ, deren erster Entwurf am 18.09.1998 in der Newsgroup de.admin.net-abuse.mail veröffentlicht wurde und die dann seit dem 15.10.1998 unter dem Titel “E-Mail-Header lesen und verstehen” dort über viele Jahre lang monatlich erschien.

Text- und HTML-Version

Natürlich sollte es zu der monatlich geposteten FAQ auch eine Web-Version geben, die bereits im Oktober entstanden war und deren URL im November 1998 das erste Mal in der FAQ genannt wurde. Und natürlich sollte diese Version auch mit allem Annehmlichkeiten, die HTML für Optik und Funktion bietet, also namentlich Formatierungen und Verlinkungen, ausgestattet sein. Das bedeutete dann umgekehrt aber auch, dass zwei völlig getrennte Versionen desselben Textes zu pflegen waren; insbesondere bei größeren Änderungen und Ergänzung keine wirklich gute Idee. Es musste also eine andere Lösung her: die eine Fassung sollte aus der anderen Fassung generiert werden, oder ggf. beide Fassungen aus demselben Rohtext.

HTML-Dokumente aus Textdokumenten erzeugen

Da mir das Usenet als Publikationsmedium (damals) deutlich näher lag, hatte ich zuerst den Gedanken, die Webseite - also das HTML-Dokument - zumindest im wesentlichen aus dem Textdokument der geposteten FAQ zu erzeugen. Bei entsprechenden Recherchen stieß ich dann auch auf das Tool AscToHTM, das genau diesem Zweck diente und sich auch insbesondere an FAQ-Autoren richtete. Eine Zeit lang habe ich damit auch gearbeitet (und das erzeuge HTML-Dokument dann quasi mit Header und Footer versehen, um es optisch und organisatorisch - Navigation! - in meine damalige Webseitenstruktur einzubinden), aber so wirklich überzeugend war das nicht. Es bedurfte einiger Kompromisse im Layout des geposteten Textes, um die HTML-Generierung überzeugend hinzubekommen, und der Aufwand war doch vergleichsweise groß.

Textdokumente aus HTML-Dokumenten erzeugen

Daher habe ich mich - theoretisch im übrigen völlig richtig - in der Folge davon überzeugen lassen, dass die Vorgehensweise, aus (letztlich) unstrukturiertem Text strukturierten Text (mit Markup) zu erzeugen, bereits gedanklich verfehlt ist und keinen dauerhaften Erfolg haben könne: HTML enthält gegenüber text/plain zusätzlichen Informationsgehalt, Struktur, Markup eben, und aus der Gestaltung des Rohtextes das Markup zu “erraten”, ist keine brauchbare Lösung. Daher bin ich danach dann eben den umgekehrten Weg gegangen und habe beschlossen, dass nunmehr die Webversion der FAQ das “Master-Dokument” (oder die Quelle) sein sollte und ich den geposteten Text daraus erzeuge. Information und optische Gestaltung zu kürzen sollte ja vergleichsweise trivial sein. — Ganz so war es dann erwartungsgemäß doch nicht, denn auch der gepostete “reine” Text sollte ja einigermaßen apart formatiert sein, mit dem was, man an “Formatierungen” in E-Mail und Usenet so gewohnt ist: Zitate eingeleitet mit “|” am Zeilenfang, Hervorhebungen und Betonungen durch *Sternchen* o.ä. und dieser Dinge mehr. Für den Anfang half dazu html2text, damals in C++ geschrieben, mittlerweile durch den verstorbenen Aaron Swartz auch in PYthon reimplementiert, aber ganz zufrieden war ich mit dem Output noch nicht.

Einiges Experimentieren führte dann zu dem folgenden Workflow:

  1. wget http://th-h.de/faq/$1 -O output.html
  2. html2text -nobs -width 70 -rcfile html2text.rc output.html > output.txt
  3. ./wrap.pl < output.txt > wrapped.txt

Und wrap.pl, das (daher der Name) vor allem für den Umbruch auf 70 Zeichen pro Zeile unter Beachtung von (nicht zu umbrechenden Zitaten) zuständig war, sah folgendermaßen aus:

  1. #!/usr/bin/perl</p>
  2.  
  3. <p>use Text::Wrap qw(&amp;wrap $columns);
  4. $columns = 70;</p>
  5.  
  6. <p>while (&lt;>) {
  7.  if (/[-\/]$/) {
  8.   ($zeile, $rest) = /(.+\s)(\S+)$/;
  9.   print &#8220;$zeile\n&#8221;;
  10.   JOINLOOP: while (&lt;>) {
  11.    $rest .= $_;
  12.    last JOINLOOP if (/^$/);
  13.   }
  14.   $rest =~ s/\n/ /g;
  15.   $_ = wrap(&#8221;, &#8221;, $rest).&#8221;\n&#8221;;
  16.  };
  17. print $_;
  18.  if (/^[|>:]/) {
  19.   QUOTELOOP: while (&lt;>) {
  20.    chomp;
  21.    if (/^$/) {
  22.     print &#8220;\n&#8221;;
  23.     last QUOTELOOP;
  24.    } elsif (/^[|>:]/) {
  25.     print &#8220;\n$<em>&#8221;;
  26.    } else {
  27.     print $</em>;
  28.    }
  29.   };
  30.  };
  31.  print &#8220;\n&#8221;;
  32. };

Das ließ sich jetzt durchaus automatisieren; andererseits gefiel es mir nicht wirklich, dass die Quelle des Textes nun ein HTML-Dokument war und ich erst längere Konversionsprozesse laufen lassen musste, um zu überprüfen, ob auch die (aus meiner Sicht immer noch primäre) Textfassung ordentlich aussah. Und HTML schreiben ist auch deutlich aufwendiger als “Klartext”, selbst wenn man sich durch geeignete Editoren beim Einfügen der passenden Tags (und deren Schließen!) unterstützen lässt.

Die Lösung?

Am Ende habe ich, glaube ich, einfach wieder beide Texte getrennt gepflegt oder, wahrscheinlicher, die FAQ (erst einige Zeit nicht mehr richtig aktualisiert und dann) gar nicht mehr gepostet; sowohl das Spam-Problem (jedenfalls der Wunsch, Spam nachzuverfolgen und zu melden) als auch das Usenet waren dabei, in die Bedeutungslosigkeit abzurutschen.

What would I today do?

(Ja, das ist kein Englisch. Nein, das ist Absicht. Ja, das spielt auf WWJD an.)

Inzwischen sind bald 16 Jahre ins Land gegangen, und es gibt damit natürlich ganz andere technische Möglichkeiten, dieses Problem zu lösen. Über manche habe ich zwischendurch nachgedacht, bspw. über Docbook und die zugehörige Toolchain, wenn ich mich recht erinnere, sogar einmal kurz damit gebastelt, aber mich nie ernsthaft damit beschäftigt. Richtig lange, umfangreiche Texte würde ich heute vermutlich in AsciiDoc zu schreiben versuchen. Beides sind Varianten der Technik “mehrere Formate aus einem Quelltext erzeugen”.

Markdown

Insbesondere für kürzere Texte und als generische Lösung bietet sich aber mittlerweile sozusagen ein Königsweg an, der auch entsprechende Verbreitung gefunden hat: Markdown. Die Idee setzt wieder dort an, wo auch ich damals - ganz instinktiv - angefangen hatte, nämlich bei der Erzeugung eines HTML-Dokuments aus einem entsprechend formatierten Textdokument, wobei aber eben durchaus “optische” Formatierungen eingebaut werden, die sich erkennen, parsen und in strukturiertes Markup umsetzen lassen. Wir kennen das - mittlerweile - auch aus Wikis. Das schöne an Markdown ist dabei, dass sich die Formatierungen dem E-Mail- und Usenet-Nutzer zumeist unmittelbar erschließen und die Syntax leicht erlernbar ist, die Texte selbst weitgehend lesbar bleiben und keiner großen Nachbearbeitung mehr bedürfen und auch (insbesondere bei der Verwendung von Erweiterungen wie Markdown Extra oder MultiMarkdown) nahezu alle Formatierungen, die man sich im generierten HTML nur wünschen kann, machbar sind. Wenn man die Möglichkeiten dazunimmt, die modernes CSS bei der optischen Gestaltung von Webseiten bietet, bleiben kaum mehr Wünsche offen.

Ein Beispiel

Für längere oder komplexere Texte wird man sich möglicherweise ergänzende Gedanken machen müssen, aber zumindest kurze Postings lassen sich so ohne großen Aufwand elegant ins Web stellen. So sieht bspw. der gepostete und leicht lesbare Text Willkommen in de.etc.notfallrettung! auch in der Webversion entsprechend aus, und diese Webversion kann jederzeit automatisiert erzeugt werden. Ich plane durchaus, auch meine längeren FAQs - die bisher auch im Web nur als Textversionen abrufbar sind - zukünftig auf diese Weise formatiert verfügbar zu machen, nehme aber an, dass insoweit noch einige Nacharbeiten erforderlich sein werden.

Weitere Vorteile

Insbesondere in Verbindung mit Versionsverwaltungssystemen wie Git zahlt es sich m.E. darüber hinaus aus, wenn der Quelltext möglichst gut lesbar ist und nicht mit Formatierungen oder HTTML-Tags überladen ist; aus einem Markdown-Dokument kann ich überdies bei jeder Änderung automatisch den zu postenden Text und die Webversion ohne zusätzlichen Aufwand aus dem Git-Repository erzeugen, kann mich also auf das Schreiben der Texte konzentrieren, ohne mich mit Routineaufgaben belasten zu müssen. (So jedenfalls die Theorie; ich strebe zukünftig auch eine entsprechende Automatisierung an. :-))

Noch ein Vorteil ist, dass Markdown (wie auch Wiki-Syntax) vergleichsweise leicht zu erlernen ist und ggf. (wie in Wikis) mit entsprechenden Editoren gekoppelt werden kann, in denen Buttons entsprechendes “Markup” erzeugen. Die Barriere für das Verfassen von Web-Texten wird damit abgesenkt.

Schlusswort

Insgesamt kann ich jedem nur raten: probiert Markdown einmal aus!

Die Texte schreiben sich darin sehr flüssig, und für die meisten CMS und Blogsysteme gibt es entsprechende Plugins. Nicht umsonst setzt bspw. auch Github sehr intensiv auf Markdown.

(Wie ich gerade bemerke, hatte ich darüber übrigens vor vier Jahren schon einmal geschrieben. Manchmal dauert eben alles etwas länger …)

Trackbacks

Netz - Rettung - Recht am : Blogs und Editoren

Vorschau anzeigen
Wer ein Blog betreibt, kennt vermutlich die Frage danach, welcher Editor für die Einträge am sinnvollsten verwendet werden sollte. Meine erste Blogengine, sunlog, bot meiner Erinnerung nach bloß ein Eingabefeld, in das man entweder HTML eingeben oder dar

Kommentare

Ansicht der Kommentare: Linear | Verschachtelt

Lars am :

Lars

Zur Umwandlung diverser Textformate (u.a. Markdown in HTML, PDF, usw.) kann ich John MacFarlanes Pandoc empfehlen.

Thomas Hochstein am :

Thomas Hochstein

Ah, danke für den Hinweis! - Den hatte ich vergessen.

Kommentar schreiben

HTML-Tags werden in ihre Entities umgewandelt.
Markdown-Formatierung erlaubt
Standard-Text Smilies wie :-) und ;-) werden zu Bildern konvertiert.
BBCode-Formatierung erlaubt
Gravatar, Identicon/Ycon Autoren-Bilder werden unterstützt.
Formular-Optionen