Im ersten Part habe ich beschrieben wie man einen eigenen Filter für Pandoc programmiert. Im zweiten Teil werde ich beschreiben, wie man eine Webseite daraus macht.

Zuerst fangen wir aber klein an:

HTML Erzeugen

Bisher haben wir nur Output, aber kein HTML erzeugt. Um jTab richtig zu benutzen müssen wir aber auch ein richtiges Template erstellen. Damit wir das nicht selber machen müssen benutzen wir das Standardtemplate von Pandoc:

pandoc -D html5 > template.html

Jetzt müssen wir nurnoch das Javascript von jTab zu dem Template hinzufügen.

[...]
<!-- recommended to avoid security warnings with SVG in IE8 -->
<meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7" />
<!-- optional: helpers to preset jtab region heights to avoid rendering jitter -->
<link type="text/css" rel="stylesheet" href="https://jtab.tardate.com/css/jtab-helper.css"/>

<!-- mandatory script includes for jtab -->
<script src="https://jtab.tardate.com/javascripts/jquery.js" type="text/javascript"></script>
<script src="https://jtab.tardate.com/javascripts/raphael.js" type="text/javascript"></script>
<script src="https://jtab.tardate.com/javascripts/jtab.js" type="text/javascript"></script>
</body>
</html>

Die Zeilen musst du an das Ende der Datei template.html hinzufügen. Danach kann man es als Argument Pandoc übergeben:

pandoc -t html --template template.html --filter ./python_filter.py tabs.md -o dist/tabs.html

Die Datei dist/tabs.html sollte jetzt unseren Output haben. Das vollständige Beispiel ist hier.

Gitlab Pages

Wenn die Seite schon bei Gitlab liegt kann man natürlich das hilfreiche Pages Feature benutzen. Das sind aber nur minimale Images, die zum Beispiel kein Python haben, welches wir aber für unseren Filter benötigen. Zum Glück ist Docker so aufgebaut, dass man existierende Images leicht erweitern kann. Im Repository liegt schon das komplette Dockerfile.

FROM pandoc/ubuntu:2.10

RUN apt-get -q --no-allow-insecure-repositories update \
  && DEBIAN_FRONTEND=noninteractive \
     apt-get install --assume-yes --no-install-recommends \
     python3\
     python3-pip\
  && rm -rf /var/lib/apt/lists/**

RUN pip3 install pandocfilters

Man kann leicht sehen, dass wir auf dem pandoc/ubuntu Image aufbauen. Es ist immer gut einen Tag (Version, 2.10) anzugeben, damit ein update der Version nicht unser Script aus dem Tritt bringen kann.

Danach installiere ich folgende Abhängigkeiten:

• Python 3
• Pip
• pandocfilters

Das Dockerfile baut man dann mit docker:

docker login registry.gitlab.com
docker build -t registry.gitlab.com/rayendumeldust/tabsite:1.0 .
docker push registry.gitlab.com/rayendumeldust/tabsite

Wichtig ist, dass man die Adresse zu seiner Registry angibt, nur dann kann Docker auch das Image hochladen.

Aber wie kommt man auf das die Änderungen im Dockerfile? Man kann ihn einfach interactiv starten und herumspielen:

docker run -ti --entrypoint /usr/bin/bash pandoc/ubuntu:latest

Um per apt Pakete installieren zu können muss man zuerst apt update ausführen. Danach kann man ungestört mit git das Repository Clonen und herumspielen, bist es funktioniert.

Continuous Integration

Gitlab hat eine eingebaute CI um Projekte zu bauen und kann automatisch nach Pages deployen. Im Repository ist ein Beispiel für die Konfiguration:

image:
  name: registry.gitlab.com/$CI_PROJECT_PATH:1.0
  entrypoint: [""]

stages:
  - build
  - deploy

pandoc:
  stage: build
  script:
    - pandoc -t html --template template.html --metadata pagetitle="Tabsite" --filter ./python_filter.py tabs.md -o dist/tabs.html
  artifacts:
    paths:
    - dist/

...

Das oben ist ein Ausschnitt der .gitlab-ci.yml Datei. Die wichtigsten Teile sind das Image und der pandoc Build Step. Wir wollen natürlich das Image aus der Gitlab Registry benutzen. Im pandoc Schritt wird unser Bash Befehl ausgeführt. Der Output in dist/ wird als Artefakt an den nachfolgenden Buildstep übergeben. Dort werden die Dateien zu den Pages hochgeladen.

Damit ist ein weiteres Teil des Projekts fertig. Man könnte jetzt sogar über die Weboberfläche neue Tabs hinzufügen. Mal schauen wie das am besten geht.