Markdown zu HTML und PDF konvertieren

Veröffentlicht: 20. Oktober 2015

Als Entwickler möchte man immer Neues machen und die Dokumentation ist eine Notwendigkeit, schon alleine aus dem Grund, dass die Software ja von jemandem genutzt werden soll. Was mich dabei bisher immer am meisten gestört hat, ist, dass ich keine „einfache“ Möglichkeit gefunden habe, den Text einmal zu schreiben und dann in verschiedene Formate zu konvertieren. Ich habe verschiede Textverarbeitungsprogramme versucht, jedoch mit überschaubarem Erfolg. Mich stören dabei die vielen manuellen Schritte, die immer erledigt werden müssen. Da ich in PHP programmiere, wäre mir eine Lösung auf Basis von PHP am liebsten. Es gibt sogar etwas, allerdings müsste ich mir dafür LaTex auf meinem MacBook installieren. Der Weg führt dann direkt in die dependency Hölle, also auch nicht wirklich etwas, das man möchte. Also mal über den Tellerrand schauen - und siehe da - mit gulp/nodejs gibt es eine Lösung. Ich persönlich mag gulp sehr gerne, vor allem, da man damit recht einfach und mit wenig Zeilen Code sehr viel machen kann. Auf dem Joomladay 2014 in Köln habe ich im Rahmen meines Buzz Words Vortrags darüber etwas ausführlicher gesprochen und ganz speziell nur über gulp auf JAB2015 in Prag. Hier nun möchte ich mich auf das Wesentliche konzentrieren.

Nutzen werde ich insgesamt 3 Gulp-Pakete: markdown, markdown-pdf und replace.

Das Ziel ist, aus einer Markdown-Datei HTML und PDF zu erzeugen. Das HTML möchte ich dann auf meiner Webseite http://babioon.com nutzen, hier soll es einfach in einen Artikel eingefügt werden und zwar ohne Nachbearbeitung. Das PDF wird zum download irgendwo anders angeboten.

Vorbereitend muss man nodejs, npm und gulp installieren. Das ist für mich nicht wirklich eine Hürde, da ich die Tools sowieso nutze. Es ist aber auch ansonsten keine Hürde, da diese Tools in knapp 5 Minuten installiert sind und es massenweise Tutorials gibt, wie man das macht. Ich gehe also davon aus, dass gulp installiert ist und man damit auch umgehen kann.

Zunächst muss man ein paar Variablen definieren (Vorsicht Javascript :-)):

var gulp        = require('gulp');
var replace     = require('gulp-replace');
var markdownpdf = require('gulp-markdown-pdf');
var markdown    = require('gulp-markdown');

Der Task für die Erzeugung des PDF ist sehr einfach:

gulp.task('pdf', function () {
    return gulp.src('addphp/babioon-add-php.md')
        .pipe(markdownpdf())
        .pipe(gulp.dest('addphp'));
});

Alle Dateien liegen in einem Verzeichnis addphp (das ist der Name der Erweiterung). Da man keine Bilder in das Markdown einfach einbinden kann, habe ich einen Server aufgesetzt, der die Bilder zur Verfügung stellt. So ist es recht einfach, das gleiche Dokument auf unterschiedliche Seiten anzubieten. Für das PDF ist das natürlich nicht von Bedeutung, aber HTML und markdown nutzen dies so konsistent.

Zu guter Letzt noch der Task für die Erzeugung des HTML.

gulp.task('markdown', function () {
    return gulp.src('addphp/babioon-add-php.md')
        .pipe(markdown())
        .pipe(replace('<hr>', '<hr id="system-readmore" />'))
        .pipe(replace(/<h([1,2,3,4,5,6])(.*?)>/g, '<h$1>'))
        .pipe(replace('<h6>', '<h7>'))
        .pipe(replace('<h5>', '<h6>'))
        .pipe(replace('<h4>', '<h5>'))
        .pipe(replace('<h3>', '<h4>'))
        .pipe(replace('<h2>', '<h3>'))
        .pipe(replace('<h1>', '<h2>'))
        .pipe(replace('</h6>', '</h7>'))
        .pipe(replace('</h5>', '</h6>'))
        .pipe(replace('</h4>', '</h5>'))
        .pipe(replace('</h3>', '</h4>'))
        .pipe(replace('</h2>', '</h3>'))
        .pipe(replace('</h1>', '</h2>'))
        .pipe(gulp.dest('addphp'));
});

Auch nicht wirklich Rocket Science. Nach dem Aufruf von markdown() hat man das HTML Dokument schon, danach ersetze ich nur noch ein paar HTML tags, damit ich das Ergebnis einfach per copy paste einfügen kann. Voila!

Über den Tellerrand schauen, kann einem jede Menge Zeit ersparen

Link zu Github mit den Sourcen

Alle Texte lizensiert als WTFPL. © 2013