markdown-fo-transformer

markdown-fo-transformer ist eine Java-Bibliothek, die Markdown in das Format XSL-FO (Extensible Stylesheet Language – Formatting Objects) übersetzt. Die erzeugten XSL-FO-Abschnitte werden mithilfe der Bibliothek in ein XSL-FO-Template eingefügt, das z.B. Informationen über das Seitenformat enthält. Das Gesamtergebnis kann dann mit einem XSL-FO-Prozessor wie Apache FOP weiter verarbeitet werden, z.B. kann ein PDF-Dokument daraus erzeugt werden.

Der Transformationsprozess kann zusätzlich durch Einfügen von Stil-Informationen und Parametern beeinflusst werden. Damit können z.B. Fonts, Schriftgrößen oder Abstände gesteuert werden.

Beispiele für XSL-FO-Templates sind hier zu finden.

Markdown

Markdown ist ein einfaches Text-Format zur Formatierung von Dokumenten. Es wird z.B. zum Schreiben der Wikipedia-Seiten benutzt. Die bei der Transformation unterstützten Elemente werden in den folgenden Abschnitten beschrieben.

Absätze

Ein Absatz besteht aus beliebig vielen beliebig langen Zeilen mit Text. Innerhalb eines Absatzes darf sich keine Leerzeile befinden, da Leerzeilen zum Beenden eines Absatzes benutzt werden. Der Umbruch erfolgt automatisch.

Zeilenumbrüche

Ein Zeilenumbruch kann in einem Absatz erzwungen werden, indem entweder eine Zeile mit zwei oder mehr Leerzeichen beendet wird oder an der Stelle des Umbruchs <br> eingefügt wird.

Hervorhebungen

Einzelne Worte oder kurze Textteile können auf mehrere Weisen hervorgehoben werden, indem sie durch besondere Zeichen eingeschlossen werden:

Ein einzelner “*” oder “_” für kursiven Text
Doppelte “**” oder “__” für Fettdruck
Ein Rückwärts-Apostroph (Backtick) für grau hinterlegten Text in Monospace-Font

Überschriften

Überschriften können auf zwei Weisen festgelegt werden:

Textzeilen, unter denen sich eine weitere Zeile befindet, die nur aus dem Zeichen ‘=’ oder dem Zeichen ‘-’ besteht. Das ‘=’ erzeugt eine Überschrift mit etwas größeren Zeichen.
Textzeilen, die mit einem bis 4 Zeichen ‘#’ beginnen. Ein einzelnes ‘#’ erzeugt große Überschriften, mit mehreren werden die Titel kleiner.

Listen

Listen bestehen aus einem Absatz, bei dem die erste Zeile mit “* " oder “1. " beginnt. Ersteres beginnt eine Spiegelstrichliste, zweites eine Aufzählung. Für jeden neuen Punkt muss eine neue Zeile wieder mit demselben Prefix geschrieben werden.

Listen können verschachtelt werden, indem die Zeilen eingerückt werden. Innerhalb der Texte sind Zeilenumbrüche erlaubt.

Definitions-Listen

Diese besondere Form der Liste erlaubt es, Erklärungen zu Begriffen zu schreiben. Der Begriff wird dabei hervorgehoben und die Erklärung etwas eingerückt. Im Markdown-Text sieht das so aus:

Begriff 1
: Erklärung zu Begriff1

Begriff 2
: Erklärung zu Begriff 2

Links

Links können im folgenden Format in das Dokument eingefügt werden:

[<text>](<url>)

<text> ist der Text, der dargestellt werden soll, <url> der Link, dem beim Klick auf den Text gefolgt werden soll. Wenn <text> leer ist, wird die URL dargestellt.

Horizontale Linie

Eine Zeile mit drei oder mehr ‘-’, die von Leerzeilen umrandet ist, erzeugt eine horizontale Linie.

Bilder

Bilder können auf folgende Weise in ein Markdown-Dokument eingefügt werden:

![](/pfad/zum/bild.jpg)

Die in anderen Markdown-Dialekten unterstützten Alt-Text sind hier ohne Funktion. Die unterstützten Grafik-Formate sind vom verwendeten XSL-FO-Renderer abhängig. JPG und PNG sind immer erlaubt.

Code-Blocks

Textabschnitte, die in Zeilen mit 3 Rückwärts-Apostrophs (Backticks) eingeschlossen sind, werden ohne Änderung des Layouts in die Ausgabe übernommen. Solche Blocks werden in Monospace-Font gesetzt und hellgrau hinterlegt.

Tabellen

Tabellen bestehen aus einer Überschriftenzeile, einer Ausrichtungszeile und beliebig vielen Zeilen mit Inhalt. In allen Tabellenzeilen werden die einzelnen Spalten durch ‘|’ getrennt. ‘|’ am Zeilenbeginn und -ende sind optional, wenn die Tabelle mehr als 2 Spalten hat.

In der Ausrichtungszeile enthält jede Spalte 3 oder mehr ‘-’. Die Zahl der ‘-’ steuert das Verhältnis der Spaltenbreiten. Davor und dahinter kann jeweils ein ‘:’ stehen. Steht das ‘:’ nur links oder nur rechts, gibt es die Ausrichtung der Spalte an, bei zwei ‘:’ wird der Spalteninhalt zentriert. Ohne ‘:’ ist die Ausrichtung undefiniert.

Einzelne Zellen kann man über mehrere Spalten strecken, indem am Zellenende mehr als ein ‘|’ ohne Abstand gesetzt wird.

Statt dieser einfachen Tabellen kann durch die Verwendung von Tabellen-Stilen das Aussehen detailliert eingestellt werden, z.B. können Rahmen gezeichnet werden.

set-text

Mit dieser Operation können auch einfache Texte überall im XSLFO-Template geändert werden, z.B. Seitenüberschriften oder Fußzeilen. Im template muss die Position mit einem id-Attribut an einem Element gekennzeichnet sein. Diese Operation setzt dann den Text des Elements.

Im Markdown-Text ist eine Zeile in folgendem Format notwendig:

*[set-text]: <name>=<text>

<name> muss durch einen Namen eines id-Attributs ersetzt werden, <text> durch den Text, der als Inhalt dieses Elements gesetzt werden soll

Beispiel

Im Folgenden findet sich ein Markdown-Text und seine Darstellung im Druck darunter.

Markdown-Beispiel
=================

Dieses ist ein Absatz.
Wie man sieht, wird der Umbruch automatisch gemacht.
Man kann einfach jeden Satz auf einer neuen Zeile beginnen.
Längere Sätze, so wie diesen hier
kann man aber auch auf beliebig viele Zeilen verteilen.
<br> Es können auch manuell Umbrüche eingefügt werden

Ein weiterer Absatz wird durch eine **Leerzeile** abgetrennt.


Spiegelstrichliste
----------

* Apfel
* Banane
  * Einrückung
* Ein Listeneintrag kann sich auch
  über mehrere Zeilen erstrecken

Aufzählung
----------

1. Messer
1. Gabel
5. Die Zahl am Zeilenanfang spielt keine Rolle

Tabelle
-------

| Tabelle            | links        |         mittig         | rechts |
|--------------------|:-------------|:----------------------:|-------:|
| Zeile 1            | Text         |       mehr Text        |   1,00 |
| Zeile 2            | Beschreibung | Noch eine Beschreibung |   2,00 |
| Dieser **fette Text und lange** erstreckt sich über 3 Spalten      |||   3,00 |

Markdown-Beispiel