Netz - Rettung - Recht (Artikel mit Tag markdown)

Markup mit HAML

nospam@example.com (Thomas Hochstein) — Mon, 08 May 2017 07:15:00 +0000

Websites bestehen - hoffentlich - in der Regel aus (wenigen) Templates, die dann mit (vielen verschiedenen) Inhalten gefüllt werden. So arbeiten Blogs und CMS, so arbeitet auch ein static site generator. Die Templates können dabei HTML-Dateien sein - müssen es aber nicht, wie ich schon anno 2015 beschrieb.

Bei der Arbeit mit meinen Webseiten habe ich mit HTML-Templates angefangen, die ich dann in der Regel mit Markdown gefüllt habe - oder, um in der Diktion von nanoc, dem von mir verwendeten static site generator, zu bleiben: die Layouts in layouts/ waren HTML-Dateien, die Inhalte in content/ in der Regel Markdown, beides (soweit erforderlich) kombiniert mit embedded ruby (ERB). Beim Compilieren durchliefen die Layouts dementsprechend einen ERB-Filter, die Inhalte zwei Filter (Markdown und ERB).

Direkt mit HTML macht die Arbeit aber - gerade bei ein wenig komplexeren Gestaltungen - auf die Dauer nur wenig Spaß: ständig muss man Tags öffnen und schließen (gut, dabei unterstützen Editoren), und die Übersicht leidet. Daher habe ich mich nach kurzer Zeit entschieden, statt auf HTML auf HAML zu setzen, eine Template-Sprache, die von HTML abstrahiert.

Ein typisches Seitengerüst wie

<!DOCTYPE html>
<html lang='de'>
  <head>
    <meta charset='utf-8'>
    <meta content='IE=edge' http-equiv='X-UA-Compatible'>
    <meta content='width=device-width, initial-scale=1' name='viewport'>
    <title><%= @item[:title] %></title>
  </head>
  <body>
    <header>
      <div class='header-container'>
        <div class='row'>
           [...]
        </div>
      </div>
    </header>
    <div class='main'>
      <h1>Überschrift</h1>
      <p>
        Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed
        diam nonumy eirmod tempor invidunt ut labore et dolore magna
        aliquyam erat, sed diam voluptua. At vero eos et accusam et
        justo duo dolores et ea rebum. Stet clita kasd gubergren, no
        sea takimata sanctus est. 
      </p>
    </div>
    <footer class='footer'>
      [...]
    </footer>
  </body>
</html>

sieht in HAML so aus:

!!!
%html{:lang => "de"}
  %head
    %meta{:charset => "utf-8"}
    %meta{:content => "IE=edge", "http-equiv" => "X-UA-Compatible"}
    %meta{:content => "width=device-width, initial-scale=1", :name => "viewport"}
    %title #{@item[:title]}
  %body
    %header
      .header-container
        .row
          [...]
    .main
      %h1 Überschrift
      %p
        Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed
        diam nonumy eirmod tempor invidunt ut labore et dolore magna
        aliquyam erat, sed diam voluptua. At vero eos et accusam et
        justo duo dolores et ea rebum. Stet clita kasd gubergren, no
        sea takimata sanctus est. 
    %footer
      [...]

Das ist kürzer, klarer strukturiert - und die logische Struktur wird unmittelbar erkennbar. Außerdem wird das Ende eines Elements nicht durch ein schließendes Tag, sondern das Zeilenende (beziehungsweise das Ende einer Einrückungsebene) gekennzeichnet. HAML schließt Tags im generierten HTML daher selbständig. Nie mehr vergessene Tags, die sich öffnen, aber nicht wieder schließen! Fehler kann man im Prinzip nur noch beim Einrücken machen - aber fehlerhafte Einrückungen führen zu einem Fehler beim Compilieren und werden daher sofort erkannt. Zudem erhält das aus dem Template generierte HTML wunderbare Einrückungen, die es ebenfalls gut lesbar machen.

Für Templates ist HAML demnach hervorragend geeignet - für Inhalte allerdings nicht so sehr. Die große Stärke - die klaren Einrückungen - wird bei Texten, die immer wieder innerhalb von Blöcken Textauszeichnungen enthalten, zu einer großen Schwäche.

Man denke an folgendes Beispiel:

<p>
  Lorem ipsum dolor sit amet, consetetur <strong>sadipscing</strong>
  elitr, sed diam nonumy eirmod tempor invidunt ut labore et
  <em>dolore magna</em> aliquyam erat, sed diam voluptua. At
  <a href="https://netz-rettung-recht.de/vero/"><strong>vero</strong></a> eos et accusam et justo duo
  dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus
  est. 
</p>

Das sieht in HAML dann so aus:

%p
  Lorem ipsum dolor sit amet, consetetur
  %strong sadipscing
  elitr, sed diam nonumy eirmod tempor invidunt ut labore et
  %em dolore magna
  aliquyam erat, sed diam voluptua. At
  %a{:href => "/vero/"}
    %strong vero
  eos et accusam et justo duo
  dolores et ea rebum. Stet clita kasd gubergren, no sea takimata
  sanctus est.

Das ist … weniger schön, und beim Schreiben nicht mehr angenehm, sondern schnell die Hölle.

Es fragt sich also, was man am besten tut, wenn Markdown allein für Inhalte nicht genügt, weil es bspw. keine Elemente wie <section> oder  kennt und auch Tabellen nicht ohne weiteres abgebildet werden können. Man könnte natürlich wieder auf HTML zurückgreifen, das sich bekanntlich mit Markdown mischen lässt.

Oder man nutzt ein weiteres Feature von HAML: es unterstützt nämlich Filter, d.h. die Verwendung anderer Markupsprachen innerhalb eines Templates. So kann man die Verwendung von HAML auf die Templates und Strukturen beschränken und die Inhalte - bspw. - in Markdown beisteuern:

  %body
    %header
      .header-container
        .row
          [...]
    .main
      %h1 Überschrift
      :markdown
        Lorem ipsum dolor sit amet, consetetur **sadipscing** elitr,
        sed diam nonumy eirmod tempor invidunt ut labore et *dolore
        magna* aliquyam erat, sed diam voluptua. At [**vero**](/vero/)
        eos et accusam et justo duo dolores et ea rebum. Stet clita
        kasd gubergren, no sea takimata sanctus est.
    %footer
      [...]

Best of both worlds!

Außerdem unterstützt HAML embedded ruby - statt HTML-Templates und Markdown-Inhalten bleiben also nur noch .haml-Dateien, die einen HAML-Filter durchlaufen. Fertig - Markdown und ERB gibt es quasi gratis dazu. (Und Textile, LESS, SASS und vieles andere, wenn man das möchte, auch.)

Serendipity und das Markdown-Plugin

nospam@example.com (Thomas Hochstein) — Wed, 19 Apr 2017 07:55:00 +0000

Bereits seit dem Relaunch meines Blogs anno 2014 nutze ich - wie schon berichtet - Markdown zur Eingabe meiner Blogbeiträge. Ich entwerfe sie in der Regel in einem externen Editor (MarkdownPad auf meinen Rechnern oder online mit Draft, wenn ich unterwegs bin) und kopiere sie dann in das Backend von Serendipity, getrennt in “Eintrag” und “erweiterter Eintrag”. Dabei nutze ich seit einigen Monaten “Eintrag” nur noch als Teaser, mit der Folge, dass die Beiträge auf der Startseite und bei Suchergebnissen auch nur noch “angeteasert” werden; bringt mehr Übersicht und eine handlichere Startseite, erfordert andererseits aber für jeden Beitrag einen weiteren Klick, um ihn zu lesen, ermöglicht es also nicht ohne weiteres, sich “an einem Stück” durch das Blogarchiv zu lesen.

Sei dem, wie dem sei - mir geht es heute um das Markdown-Plugin für Serendipity namens serendipity_event_markdown. Intern verwendet das Plugin PHP Markdown von Michel Fortin und bietet (aus mir nicht ganz klaren, wohl vor allem historischen Gründen) zwei Varianten (oder, wie es in der Konfiguration heißt: Versionen) des Markdown-Parsers an: einmal ein “klassisches” Plugin “für Wordpress, Smarty, etc.”, das aber durch den Autor seit Februar 2013 nicht mehr unterstützt wird, und die PHP Markdown Lib, die immerhin 2015 zuletzt released wurde. Auch werden zwei “Geschmacksrichtungen” unterstützt: das originale Markdown von John Gruber und eine erweiterte Version, PHP Markdown Extra, von Michael Fortin selbst, die - ähnlich wie MultiMarkdown oder GitHub Flavored Markdown - einige Erweiterungen unterstützt, namentlich Tabellen, Definitionslisten, HTML-IDs und -Klassen und Fußnoten.

Ich habe bisher immer die PHP Markdown Lib verwendet, mich aber darüber gewundert, dass - trotz Aktivierung von Markdown Extra in der Konfiguration - die erweiterten Funktionen nicht richtig umgesetzt wurden. Im Nachgang zum Serendipity-Camp 2017 hatte ich mir vergangene Woche dann einmal den entsprechenden Code des Plugins näher angesehen und den Grund für das Problem gefunden: das “klassische” Plugin stellt, je nach eingebundener Markdown-Geschmacksrichtung, über dieselben Funktionsaufrufe Markdown und Markdown Extra bereit, je nachdem. Die PHP Markdown Lib hingegen bietet zwei verschiedene Funktionsaufrufe; es muss also nicht nur die richtige Library eingebunden werden, es muss zusätzlich auch die Markdown-Extra-Funktion (und nicht die Markdown-Funktion) aufgerufen werden, damit die zusätzlichen Möglichkeiten von Markdown Extra zur Verfügung stehen.

Das habe ich dann im Code entsprechend umgesetzt und zugleich die derzeit aktuellste Version der PHP Markdown Lib in das Plugin eingebunden. Jetzt lassen sich endlich mit einfach Mitteln “Sprungmarken” im Text setzen und Fußnoten verwenden (und Tabellen usw. natürlich auch)!

Die Verwendung von Fußnoten zieht noch zwei weitere Probleme nach sich, die beide darin begründet liegen, dass die Fußnote im Text mit einem Link zum Fußnotentext hinterlegt wird und der Fußnotentext - am Ende des Beitrags eingefügt - dann einen Link zurück zur Fußnoten enthält. Eines der Probleme entsteht, wenn (bspw. auf der Startseite oder in einem Suchergebnis) mehrere Beiträge angezeigt werden, die Fußnoten enthalten. Dann gibt es nämlich mehrere identische Fußnoten (bspw. “1”) und damit auch mehrere identische Sprungmarken (IDs), und ein Klick auf die Fußnoten führt in der Regel zum falschen Fußnotentext, nämlich immer zu dem der ersten Fußnote “1” auf der Seite. Dieses Problem lässt sich lösen, indem die Fußnotenlinks jeweils um die interne Nummer des Beitrags ergänzt werden, zu dem sie gehören. Für die PHP Markdown Lib habe ich das implementiert; das “klassische” Plugin ermöglicht eine solche Funktionalität hingegen nicht (und müsste ggf. gepatcht werden, wenn man es nicht schlicht aus dem Code entfernen will, was m.E. näher liegt).

Das andere Problem ergibt sich aus der Designentscheidung, in Serendipity den “Eintrag” und den “erweiterten Eintrag” als getrennte Textfelder zu realisieren. Das führt dazu, dass auch für Plugins “Eintrag” und “erweiterter Eintrag” getrennte Textelemente sind, und dementsprechend Fußnoten im “Eintrag” an dessen Ende - also vor dem “erweiterten Eintrag” eingefügt werden. Andererseits hat das den Vorteil, dass man nicht das Problem von Wordpress und anderen Blogsystemen hat, die “Eintrag” und “erweiterten Eintrag” einfach durch eine spezielle Markierung wie  voneinander trennen; dann kann es nämlich passieren, dass man die Fußnote sieht, aber den Fußnotentext nicht anspringen kann, da dieser hinter  steht und daher nicht angezeigt wird.

Insgesamt freue ich mich aber, dass Markdown Extra nun auch in Serendipity zuverlässig zur Verfügung steht.¹ (Wie soll man auch bloß Texte verfassen können, ohne sie mit Dutzenden, ja Hunderten von Fußnoten zu schmücken?! Einem Juristen muss das schon von Berufs wegen völlig unverständlich sein.)

Jedenfalls, sobald der entsprechende Pull Request akzeptiert wird. :-) ↩︎

Markup-Formate konvertieren

nospam@example.com (Thomas Hochstein) — Mon, 16 Feb 2015 05:55:00 +0000

In meiner Reihe “Webdesign anno 2015” habe ich versucht, einen Überblick über Techniken und Tools zu geben, die letztlich jedermann die Gestaltung moderner, gut aussehender Webseiten ermöglichen. Das hatte natürlich einen konkreten Anlass: ich bin dabei, allmählich und sehr langsam - im Rahmen der mir bleibenden zeitlichen Möglichkeiten - verschiedene ältere Webpräsenzen zu überarbeiten und inhaltlich wie optisch und technisch auf den heutigen Stand zu bringen.

Eine große Erleichterung ist dabei die automatische Konvertierung von “klassischem” HTML in HAML und/oder Markdown. Ein machtvolles Werkzeug für solche Konvertierungsaufgaben ist pandoc; es geht aber oft auch eine Nummer kleiner, ganz simpel per cut & paste online:

Convert HTML to HAML
HTML zu Markdown konvertieren:
to-markdown

Wenn nur eine Handvoll Seiten - oder Teile einer Seite - zu konvertieren sind, reicht (mir) das vollständig aus.

Generatoren für statische Websites

nospam@example.com (Thomas Hochstein) — Fri, 22 Aug 2014 08:30:00 +0000

Ganz früher bestand eine Homepage, bestanden Webseiten allgemein im wesentlichen aus HTML-Dokumenten. Auf dem Weg zum Web 2.0 kamen zunächst CGI-Scripts für bestimmte Anwendungen auf; insbesondere aber mit der Verbreitung von PHP wurden Webseiten deutlich interaktiver. Blogs, Gästebücher, Kontaktformulare wären anders auch kaum vorstellbar. Nicht immer aber ist Interaktivität wirklich erforderlich. Manche eigentlich statische Seite wird nur deshalb dynamisch via PHP - oder auf vergleichbare Weise - erzeugt, weil es so bequem ist, die Erstellung einer Navigation und der Grundstruktur der Seiten zu automatisieren und Änderungen nur an einer Stelle vornehmen zu müssen. Das kann durch Installation eines CMS - oder eines dafür “zweckentfremdeten” Blogs oder Wikis - erfolgen; man kann auch wie ich schlicht die bisherigen HTML-Dokumente durch PHP-Scripts ersetzen, die im wesentlichen nichts anderes tun als vorgefertigte Funktionen für die Generierung des Seitengerüsts und der Navigation aufzurufen und ansonsten praktisch nur aus HTML bestehen. Meistens wäre es aber eigentlich gar nicht erforderlich, die Webseiten für jeden Aufruf neu zu generieren, weil sie sich nicht oder doch nur selten ändern. Ausreichend wäre es vielmehr, die Erstellung der an und für sich statischen Seiten aus Vorlagen - Templates - zu automatisieren und dabei ggf. auch automatisch die nötige Navigation zu erstellen.

Das leisten - in verschiedensten Variationen - static site generators, also Scripts oder Programmpakete, die man mit Schablonen (Templates) und Inhalten füttert und die daraus - ergänzt um eigene Programmschnipsel - die fertige Website erstellen. Vorteilhaft daran ist, dass die Webpräsenz im wesentlichen aus statischen HTML-Seiten bestehen kann, nur dort durch Scripts ergänzt, wo das auch tatsächlich für Interaktivität notwendig ist. Auf dem Webserver wird die Last deutlich verringert, weil nicht für jeden Seitenaufruf ein PHP-Interpreter gestartet werden muss; auch bestehen weniger Angriffsmöglichkeiten, weil kein ausführbarer Code mehr “live” auf dem Webserver laufen muss. Eine gewisse Interaktivität lässt sich auch durch tägliche, halbtägliche oder sogar stündliche Neuerzeugung der Webseiten erreichen; das macht für ein Forum oder auch ein Blog mit Kommentaren sicher wenig Sinn, aber wenn “nur” ein RSS-Feed oder die aktuellsten Tweets eingeblendet werden sollen, reicht das oft aus. Zudem lassen sich bspw. Kommentare auch durch externe Systeme wie Disqus vermittels Javascript einbinden.

Das Angebot an solchen Generatoren ist - wie bei Blogs, Wikis, CMS, Bugtrackern usw. - einigermaßen unüberschaubar geworden, wie man einer beliebigen Liste von Static Site Generators entnehmen kann. Gute Erfahrungen habe ich mit nanoc gemacht, mit dem auch der CCCS seine Website generiert; Jekyll wird bspw. bei GitHub genutzt, um dort Webseiten - direkt aus Git heraus - zu generieren. Der einzige Nachteil bei beiden ist ggf., dass sie in Ruby geschrieben sind und daher eigene Scripts und Erweiterungen sinnvollerweise ebenfalls in dieser Sprache zu halten sind.

Das Grundprinzip ist bei allen Generatoren immer dasselbe: Es wird ein Grundgerüst für die Seiten in Form eines oder mehrerer Templates aufgebaut, gerne in HTML 5 und “responsive”, die dabei Platzhalter oder sogar entsprechend fortgeschrittenere Funktionen enthalten. Das Design erfolgt über CSS, wobei auch CSS-Präprozessoren wie LESS oder SASS zur Anwendung kommen können. Die einzelnen Webseiten schließlich können als HTML-Dokumente, aber besser noch in einfacheren Auszeichnungssprachen wie MarkDown, Textile, Asciidoc usw. angelegt werden. Dann gibt es in der Regel noch eine Konfigurationsdatei, aus der sich ergibt, wie die einzelnen Bausteine - Templates, CSS, Seiteninhalte - “bearbeitet” und zusammengefügt werden sollen. Aus diesen Anweisungen und Bausteinen generiert der Site Generator dann statische HTML-Dokumente (oder auch PHP-Scripts, oder Dokumente, die Javascript enthalten, oder …). In der Regel sind dabei eine Vielzahl von Filtern zur Interpretation von Markdown, LESS und Co. bereits enthalten; die eigenen Seiten und Designs lassen sich daher quasi aus einem Baukasten zusammensetzen, zumal als Basis für das Grundgerüst der Seiten auf Systeme wie Bootstrap oder HTML5 Boilerplate zurückgegriffen werden kann, die eigene Schriftarten, Icons und/oder Javascript direkt mitbringen oder zumindest entsprechende Anregungen enthalten. Mit verhältnismäßig wenig Aufwand lassen sich so die eigenen Inhalte hübsch, technisch modern und auf den verschiedensten Geräten vom Smartphone über das Tablet bis zum Laptop oder großen Desktopbildschirm ansehnlich darstellen.

Wenn man möchte, kann man auch die Quelldokumente in einem Versionsverwaltungssystem wie Git verwalten und bei jeder Änderung daraus automatisch eine neue Version der Webseiten erzeugen. Auf diese Weise ist ein Blogbeitrag, aber auch eine neue Seite der eigenen Homepage schnell in Markdown geschrieben, mit einem Vorspann - mit den notwendigen Informationen wie Titel, Autor, Erstellungsdatum, Typ pp., bspw. in YAML - versehen und im Git-Repository gespeichert; daraus erzeugt dann der Generator automatisch die neue Seite und passt - gleichfalls automatisch - alle davon betroffenen anderen Seiten (Inhaltsverzeichnis/Sitemap, Navigation, RSS-Feed, …) an und erzeugt sie, soweit nötig, neu.

Ich finde das sehr praktisch für alle Anwendungsfälle, die keine “Webapplikation” darstellen, sondern im wesentlichen statische Inhalte enthalten, die sich nicht minütlich oder stündlich, sondern eher täglich, wöchentlich oder auch nur alle Jubeljahre einmal ändern. Durchaus lässt sich aber auch ein Blog so betreiben, wenn man denn die interaktiven Elemente wie Kommentare pp. “outsourced”, bspw. an Anbieter wie Disqus. Mit ausreichend Zeit - ja, genau da liegt der Knackpunkt … - plane ich, zumindest einige der von mir betreuten Webseiten in der Zukunft entsprechend umzustellen.

MarkdownPad

nospam@example.com (Thomas Hochstein) — Wed, 20 Aug 2014 06:17:00 +0000

Über Markdown habe ich in diesem Blog schon mehrfach geschrieben. Ich nutze diese simple Auszeichnungssprache nicht nur für meine Blogbeiträge, sondern auch für FAQs, die sowohl als einfacher Text - bspw. für Postings im Usenet - als auch als HTML - bspw. im Web - veröffentlicht werden sollen, als Quelle für daraus generierte Webseiten oder bei Anbietern, die gleichfalls auf diese Auszeichnungssprache setzen, wie bspw. Github.

Bislang habe ich Markdown in meinem Standardeditor Sublime Edit 2 verfasst (oder ggf. in Notetab Pro), schließlich handelt es sich letztlich um einfachen Klartext, und den Text dann veröffentlicht und notfalls einmal nachbearbeitet. Wenn ich einmal wirklich eine Vorschau sehen wollte, habe ich einen der im Web vorhandenen Online-Konverter wie Markdown Live Preview benutzt, bei dem man links in ein Fenster seinen Text einfügen kann und der rechts daneben dann live die Umsetzung in HTML darstellt. Wenn man allerdings mit einer langsamen Internetanbindung irgendwo an der Küste sitzt - oder gar offline arbeiten möchte -, ist das kein optimaler Workflow.

Daher bin ich jetzt - nach kurzer Suche über Google - auf den Markdown-Editor MarkdownPad 2 gestoßen, der einem im Prinzip das, was Markdown Live Preview online kann, offline bietet: links der Text in Markdown, rechts daneben das gerenderte HTML. Außerdem gibt es die bereits sattsam aus Web-Editoren wie in Wikis oder Blogs bekannten Buttons, mit denen man das entsprechende Markup generieren kann - eigentlich nicht nötig, weil das schöne an Markdown ja gerade ist, dass man es ganz natürlich tippen kann, aber mal ganz praktisch, wenn man nach einer Schaffenspause mal wieder ein spezielleres Markup vergessen hat und sich den Ausflug zu einer Syntaxübersicht sparen möchte. Außerdem kann man auf einfache Weise das generierte HTML direkt exportieren, wenn man das möchte.

MarkdownPad ist kostenlos; die 15 Dollar teure “Professional”-Version beherrscht u.a. Tabellen in Markdown Extra und den Export in ein PDF. Ich finde das sehr praktisch und werde dieses Tool zukünftig für meine Markdown-Texte verwenden.

Blogs und Editoren

nospam@example.com (Thomas Hochstein) — Wed, 28 May 2014 02:43:00 +0000

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 darauf setzen konnte, dass der ansonsten nicht weiter bearbeitete Text schon irgendwie ausgegeben werden würde.

Nach dem Umstieg auf Serendipity habe ich auch erst einmal den Standard-Editor verwendet, wozu braucht man schließlich WYSIWYG, wenn man HTML beherrscht? Das war auf die Dauer dann aber doch eher anstrengend: um jeden Absatz herum ... schreiben, Hervorhebungen korrekt mit ... einbauen, Links von Hand setzen … Das macht keinen wirklichen Spaß. Und der Einbau von Bildern ist von Hand auch eher eine Strafe als ein Vergnügen.

Also bin ich später auf den WYSIWYG-Editor von Serendipity gewechselt; ich glaube, ich habe sogar nacheinander verschiedene solche benutzt. So richtig zufrieden war ich damit aber auch nicht; das daraus generierte HTML erschien teilweise suboptimal, zwischendurch hatte das Gerät aufgrund irgendeiner (vermutlich von mir irrtümlich getroffenen) Einstellung die Neigung, alle Texte per -Tag mit weißem Hintergrund zu hinterlegen und Spielereien dieser Art mehr. Außerdem war es so mit nicht unerheblichem Aufwand verbunden, Einträge in einem Texteditor vorzubereiten und später per copy & paste ins Blog zu übernehmen, bedurfte es dann doch eines zweiten Schrittes, in dem Formatierungen und Links hinzugefügt wurden, wie auch lx4r in einem vergleichbaren Blogbeitrag berichtet. Wenn ich stattdessen direkt im Editor schrieb, ereilte mich gerne ein Missgeschick wie “langen Blogeintrag geschrieben, abgeschickt, mittlerweile aber ausgeloggt” (worauf Serendipity den Beitrag üblicherweise hungrig verspeist und man ihn neu schreiben darf) oder, noch schlimmer, ich komme an eine Tastenkombination, die eine Browseraktion auslöst und dann den Browser den Text verschlucken lässt. Gut, dagegen hilft Lazarus, aber der wahre Jakob ist das trotzdem nicht, ganz abgesehen davon, dass man eben so nicht sinnvoll offline arbeiten (oder auch nur die Annehmlichkeiten eines guten Texteditors nutzen) kann.

Mit dem Relaunch des Blogs habe ich auch dafür eine Lösung gefunden: ich verwende den simplen Standardeditor von Serenditpity zusammen mit dem Markdown-Plugin. Wieder eine für mich sehr hilfreiche Anwendung von Markdown. Jetzt kann ich flüssig Texte schreiben, sie ggf. per copy & paste ins Blog übernehmen und muss mich nie wieder um seltsame Formatierungen kümmern. Passt. Das ist ein Workflow, der Spaß macht.

(Um zu verhindern, dass ältere Einträge durch das Markdown-Plugin zerhackt werden, kann man dieses Plugin für die älteren Einträge - jeweils einzeln pro Eintrag - deaktivieren. Jedenfalls dann, wenn man das Plugin “erweiterte Eigenschaften für Artikel” [serendipity_event_entryproperties] installiert hat. )

Markdown: HTML aus Text erzeugen

nospam@example.com (Thomas Hochstein) — Sat, 24 May 2014 15:19:00 +0000

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:

wget http://th-h.de/faq/$1 -O output.html
html2text -nobs -width 70 -rcfile html2text.rc output.html > output.txt
./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:

#!/usr/bin/perl
use Text::Wrap qw(&wrap $columns);
$columns = 70;
while (<>) {
chomp;
if (/[-\/]$/) {
($zeile, $rest) = /(.+\s)(\S+)$/;
print “$zeile\n”;
JOINLOOP: while (<>) {
$rest .= $_;
last JOINLOOP if (/^$/);
}
$rest =~ s/\n/ /g;
$_ = wrap(”, ”, $rest).”\n”;
};
print $_;
if (/^[|>:]/) {
QUOTELOOP: while (<>) {
chomp;
if (/^$/) {
print “\n”;
last QUOTELOOP;
} elsif (/^[|>:]/) {
print “\n$”;
} else {
print $;
}
};
};
print “\n”;
};

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 …)

markdown: Text in HTML verwandeln

nospam@example.com (Thomas Hochstein) — Sun, 16 May 2010 12:17:00 +0000

Auf dem Umweg über ikiwiki - was vielleicht zukünftig einmal einen eigenen Beitrag wert ist - bin ich letzte Woche auf markdown gestoßen - ein Perl-Script, das einen strukturierten Klartext in (X)HTML verwandelt. Das ist, wie ich finde, eine tolle Sache, weil auf diese Weise der Quellcode der HTML-Seite für sich als Text lesbar bleibt. Es ist sogar möglich, auf diese Weise eine Text- und HTML-Version eines Dokuments parallel zu nutzen (um den Preis, daß Links in der Textversion etwas eigenartig wirken, und der HTML-Version eine interne Navigation fehlt).

Beispielsweise habe ich den Einführungstext in die Newsgroup de.etc.notfallrettung, der regelmäßig in die Gruppe gepostet werden soll, auf diese Weise verfaßt. Der Text - der in genau dieser Fassung auch gepostet wird - ist gut lesbar, und markdown erstellt daraus ohne weiteren Aufwand die HTML-Version. (Das erfolgt automatisch durch ein Script, das die entsprechende Fassung des Textes aus dem Git-Repository auscheckt, durch markdown laufen läßt und dann an den richtigen Ort auf meinem Webserver verschiebt.)