Die Idee, GitLab als universelles CMS zu verwenden, wurde schon an anderer Stelle ausgeführt und prägt unsere Arbeit sowohl in der OER-Produktion als auch im Projekt “Modernes Publizieren”.¹ Mit diesem Tutorial wollen wir zeigen, dass auch Einsteiger_innen schnell zu Ergebnissen gelangen können, ohne sich umfangreich in die komplexe Benutzeroberfläche von GitLab einarbeiten zu müssen.

Einleitung

Tools wie HackMD und Etherpad bieten einen entspannten Einstieg ins kollaborative Schreiben, allerdings nur für kurze Dokumente. Bei längeren Werken kann das Scrollen im Text schnell lästig werden und es steht der Schritt an, das Dokument zu modularisieren. Mit den genannten Tools hieße das, für jeden Teil oder jedes Kapitel ein eigenes Pad anzulegen und zwischen den Links hin- und herzuspringen bzw. diese Links in einem Autor_innenkollektiv zu kommunizieren. Für die Praxis ist das nicht die beste Lösung. HackMD bietet in der Referenzinstallation zwar einen Book Mode, der bspw. spontane Anthologien von Beiträgen verschiedener Autor_innen ermöglicht. Aber er hat seine Grenzen, vor allem, weil der Book Mode nicht in der freien Version von HackMD (CodiMD) verfügbar ist.

Das vorliegende Tutorial ist das Ergebnis eines fruchtbaren Austauschs unter den Projektpartner_innen im Programm Hamburg Open Science (HOS). In der Zusammenarbeit hat sich ausgehend von unserem Projekttitel “Modernes Publizieren” auch ein Diskurs entsponnen, wie andere Formen von Dokumenten (Projektanträge, Konzeptpapiere, Bücher u.ä,) kollaborativ entwickelt werden können. Wir wollen in diesem Beitrag zeigen, wie das gemeinsame Arbeiten an größeren Dokumenten im Standardwiki von GitLab mit Docker und pandoc/LaTeX möglich ist.

Wikis in GitLab

Jedes Projekt in GitLab ist standardmäßig mit einem Wiki ausgestattet. Technisch gesehen handelt es sich dabei um ein zweites Git-Repository, das neben dem Hauptrepository des Projekts existiert. Beide Repos “wissen” nichts voneinander, sind also technisch gesehen zunächst einmal unabhängig. Dass das Wiki ein Repo ist, macht sich auch in der Arbeit im Browser nicht bemerkbar. Wird es jedoch auf einen lokalen Arbeitsrechner geklont, können Wikiseiten offline komfortabel mit bewährten Editoren wie VSCodium bearbeitet werden.² VSCodium hat schon einen Git-Client eingebaut, über den die Arbeit mit dem entfernten Wiki in GitLab möglich ist.

Für Einsteiger_innen in das kollaborative Arbeiten an Texten reichen unserer Beobachtung nach die Funktionen des Wikis im Browser zunächst vollkommen aus. Das Klonen des Wikirepos übernimmt in diesem Workflow GitLab selbst im Rahmen der Pipeline, die wir bauen. Doch eins nach dem anderen.

Rollenverteilung von Hauptrepo und Wikirepo

Eigentlich ist es üblich, dass digitale Artefakte aus den Inhalten im Hauptrepo eines GitLab-Projekts generiert werden, in der Regel also Software. Wir nutzen dieses Kernfeature von GitLab für unseren Ansatz des kollaborativen Schreibens von Journalbeiträgen, wie hier im Blog schon beschrieben.

Bei unseren Experimenten zum Schreiben größerer Dokumente hat sich eine strikte Aufgabenteilung der beiden Repos eines Projekts ergeben:

• Das Repo des Wikis speichert den Inhalt, also Texte, Abbildungen etc.

• Das Hauptrepo speichert

  • verschiedene Konfigurationsdateien
  • eine optionale Literaturdatenbank
  • Zitierstile
  • ggf. weitere Dateien, die für den Bau und das Layout des finalen Artefakts notwendig sind

pandoc und LaTeX

pandoc ist ein Formatkonverter. Das Programm wird mit Textbefehlen benutzt und kann aus zahlreichen Quellformaten zahlreiche Zielformate von Dokumenten generieren. Soll am Ende ein PDF herauskommen, wird in einem Zwischenschritt das Textsatzprogramm LaTeX benutzt. Um den Funktionsumfang und die Möglichkeiten von LaTeX für Publikationsworkflows kennenzulernen, eignet sich z.B. das Buch “Einführung in LaTeX” von Herbert Voß sowie das frei verfügbare PDF zu KOMA-Script von Markus Kohm und Jens-Uwe Morawski. Es ist zulässig zu behaupten, dass alles, was mit LaTeX möglich ist, auch über pandoc gelöst werden kann. Der Vorteil ist, dass Autor_innen hauptsächlich in Markdown schreiben und besondere Darstellungen wie Tabellen oder Konfigurationen des Layouts mit LaTeX erledigt werden. Diese beiden Schwierigkeitsstufen können aber gut voneinander getrennt werden.

Im Rahmen dieses Tutorials wird es nur wenig Berührung mit LaTeX geben.

Anlegen eines Projekts in GitLab

Im GitLab an der TUHH oder auf gitlab.com legen wir zunächst ein neues Projekt mit Namen “Buchprojekt” an. Hierbei ist es unwichtig, ob dieses privat oder öffentlich ist. Eine README-Datei soll miterstellt werden.

Wir schalten anschließend über Settings > General > Visibility, project features, permissions alle unnötigen Features ab, um die Seitenleiste nicht zu überfrachten und weil wir diese Features momentan nicht brauchen.

Füllen des Wikis

Damit das Wiki eine Startseite hat, auf der ggf. Angaben zur Arbeitsweise im Wiki stehen, erstellen wir zunächst eine Seite mit dem Slug home. Diese wird später nicht Teil unseres Buches werden. Hier kann bspw. die Gliederung entworfen werden.

Nun füllen wir das Wiki wie gewohnt. Für unser Buchprojekt muss hierbei zunächst nichts anders gemacht werden als sonst. Mit Hilfe eines Blindtextgenerators erstellen wir schnell einige Seiten:

• einleitung
• hintergrund
• methode
• fazit

Die hier vorgeschlagenen Slugs ergeben im System von GitLab Dateien mit den Namen einleitung.md, hintergrund.md, methode.md und fazit.md, die später bei der Konfiguration der Pipeline angegeben werden müssen.

Die Überschriften, die wir verwenden, ergeben später die Gliederungsebenen des Dokuments und damit auch das Inhaltsverzeichnis. Beginnt bspw. jede Wikiseite mit einer #, handelt es sich dabei quasi um Kapitelüberschriften. Im Text sollten dann nur tiefere Ebenen notiert werden, also ## für eine Unterüberschrift im Kapitel. Wir denken aber, dass es eine Sache der gemeinsamen Verabredung ist, wie hier verfahren werden sollte. Experimente helfen, die gewünschte Strukturierung und Modularisierung des Buchkorpus’ zu ermitteln.

Der Seiteninhalt muss immer mit mindestens einem Zeilenumbruch abschließen. Konkret heißt das, dass mindestens einmal ENTER nach dem letzten Zeichen des Textfeldes gedrückt werden muss.

Der Grund ist, dass pandoc später die einzelnen Wikiseiten aneinander reiht. Dabei wird dann das letzte Zeichen einer Seite gefolgt von der Raute (#) der Überschrift auf der Folgeseite. Sind diese Zeichen nicht sauber getrennt, wird die Überschrift nicht erkannt.

Einbinden von Abbildungen

Abbildungen lassen sich sehr einfach in eine Wikiseite einbinden. Sie können entweder per Drag & Drop in das Editorfeld gezogen werden, oder im Editiermodus über den Link Attach a file rechts unten hochgeladen und verlinkt werden. Vorher sollte der Cursor schon in der gewünschten Zeile blinken, dann landet die Abbildung gleich an der richtigen Stelle.

Wie auf der Abbildung zu erkennen ist, speichert GitLab Bilder, die auf diese Weise hochgeladen werden, in einem Ordner mit einem zufällig generierten und schwer erratbaren Namen unterhalb des Ordners uploads. Auch wenn es sich hierbei um security by obscurity handelt, ist die Einfachheit des Vorgehens zunächst einmal unschlagbar. Der Ordner uploads befindet sich auch nicht im Wurzelverzeichnis von GitLab, sondern im Wurzelverzeichnis des Wikis und ist nur für Zugriffsberechtigte im Projekt einsehbar und manipulierbar. Beim Klonen des Wikirepos auf einen lokalen Rechner kann der Ordner uploads aufgeräumt und neu strukturiert werden.

Automatisierung der Produktion

An dieser Stelle haben wir genug Vorbereitungen getroffen, um aus den Seiten des Wikis ein Buch zu bauen. Mit der Zitation von Literatur werden wir uns später beschäftigen. Das fertige Buchprojekt, dessen Dateien im Folgenden besprochen werden, kann als offenes Repo für eigene Zwecke geklont werden.

Konfiguration einer Pipeline mit pandoc

Für die Generierung des Buches aus dem Wiki setzen wir auch hier pandoc ein, allerdings ohne den Zusatz pandoc-scholar. Wir verwenden ein Docker-Image vom Docker Hub in der Version pandoc 2.7.3. Das Image fungiert in der Prozesskette als virtueller Computer. Es enthält ein Betriebssystem und alle notwendigen Programme (auch LaTeX und pandoc/pandoc-scholar), um aus Markdown-Dateien Bücher zu bauen.³

Die .gitlab-ci.yml

Die Datei .gitlab-ci.yml ist die Anleitung, wie GitLab das Buch bauen soll. In der Datei konfigurieren wir GitLab so, dass es am Ende bei jeder Änderung im Wiki eine aktuelle Version des Buchs baut. Über den Browser kann sie im Hauptrepository angelegt werden. Wichtig ist dabei der führende Punkt im Dateinamen .gitlab-ci.yml!

image: xldrkp/pandoc:latest

build:
  before_script:
    - git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@collaborating.tuhh.de/hos/modernes-publizieren/offen/software/konfigurationen/buchprojekt.wiki.git
  script:
    - ls -la
    - cd buchprojekt.wiki
    - ls -la
    - pandoc --version
    - pandoc
      einleitung.md
      hintergrund.md
      fazit.md
      -o ../buch.pdf
  artifacts:
    paths:
      - "*.pdf"

In der ersten Zeile steht, dass die Pipeline auf dem genannten Docker-Image basieren soll. GitLab wird beim ersten Durchlauf der Pipeline etwas länger brauchen, um es herunterzuladen. Danach ist es in der Regel im Cache und das Bauen geht schneller.

Der Abschnitt build bezeichnet einen Job in der Pipeline. Es kann mehrere Jobs geben, die auch voneinander abhängen können. Für den Teil before_script ist wichtig zu wissen, was beim Durchlauf der Pipeline passiert: GitLab verwendet standardmäßig das Hauptrepo des Projekts und wendet alle Befehle der Pipeline auf dessen Dateien an. Wollen wir unser Buch aus dem Wiki bauen lassen, müssen dessen Dateien zunächst einmal dazugeholt werden.

Das erfolgt mit dem Befehl im Abschnitt before_script. Hier ist der Teil nach dem @ anzupassen. Er ist erreichbar über den Link Clone repository über der rechten Seitenleiste des Wikis. Auf der folgenden Seite muss dann “HTTPS” vor der URL ausgewählt werden. Der Kopierbutton übernimmt den kompletten Link in die Zwischenablage.

Nach dem https:// der kopierten URL muss nun gitlab-ci-token:${CI_JOB_TOKEN}@ eingefügt werden. In unserem Beispiel ergibt das die Adresse

https://gitlab-ci-token:${CI_JOB_TOKEN}@collaborating.tuhh.de/hos/modernes-publizieren/offen/software/konfigurationen/buchprojekt.wiki.git

Diese fügen wir in der .gitlab-ci.yml ein (vgl. Script oben).

Die Zeilen im Abschnitt script sind nicht alle notwendig, helfen aber zu verstehen, was in der Pipeline vor sich geht. Dabei handelt es sich um Befehle für das Linux-Betriebssystem, das unserem pandoc-Image zugrundeliegt.

Das erste ls -la listet den Verzeichnisinhalt des Hauptrepos auf, cd wechselt in das Verzeichnis, das durch das Klonen des Wikis angelegt wurde. Hierbei ist wichtig, dass ggf. auch dieser Teil entsprechend dem Namen des Projekts angepasst wird. Das zweite ls -la listet den Inhalt des Wikis auf. pandoc --version zeigt an, mit welcher pandoc-Version wir arbeiten.

Dann kommt schließlich die Anweisung für pandoc, mit der aus ausgewählten Dateien des Wikis das Buch gebaut wird. Hierbei stehen alle Dateien, die aus dem Wiki einbezogen werden sollen, der Übersichtlichkeit untereinander. Die letzte Zeile -o ../buch.pdf ist ein pandoc-Parameter, der besagt, dass die Ausgabe (“o” = “output”) in die Datei buch.pdf erfolgen soll.

Der Abschnitt unter artifacts gibt an, dass alle entstandenen Dateien mit der Dateiendung pdf von GitLab aufbewahrt werden, bevor der Docker Container mit pandoc verworfen wird.

Nach dem Anlegen der Datei will GitLab die Pipeline schon anstoßen, weil es diese Datei jetzt gibt. Das kann aber noch nicht funktionieren, weil bisher kein Runner zugeordnet wurde. Ein Runner beobachtet Ereignisse wie das Ändern von Dateien und läuft dann los, um die Jobs der Pipeline zu erledigen.

Einen GitLab Runner zuordnen

Über die Sidebar Settings > CI/CD > Runners kann dem Projekt ein Shared Runner zugewiesen werden, sofern die GitLab-Installation das bietet.

Nun kann die Pipeline manuell über die Sidebar CI/CD > Pipelines und dann über den Button Run Pipeline, anschließend nochmals Run Pipeline gestartet werden.

Artefakte anschauen und sichern

Wenn alles funktioniert hat, ist der letzte Job mit einem grünen passed gekennzeichnet und zeigt ein Logfile wie folgt:

Nach Klick auf das build-Label lässt sich über die Button Download und Browse das gebaute PDF online ansehen oder herunterladen.

Wer das Tutorial nicht mitgebaut hat, kann die erste Version hier ansehen bzw. herunterladen.

Literatur, individuelle Schriften und ein Titelblatt

Gerade im wissenschaftlichen Kontext ist eine gute Literaturverwaltung wichtig. Wir können das an dieser Stelle mit einer Datei references.bib im Hauptrepo lösen, auf die wir uns in unseren Wikiseiten beziehen. Der Filter pandoc-citeproc ergänzt unseren Technikstack ausgezeichnet um diese Funktion. Als Programm zur Literaturverwaltung kommt Zotero zum Einsatz, weil die Software plattformübergreifend und kostenlos funktioniert und die Onlineversion für das kollaborative Arbeiten mit Literatur sehr gut geeignet ist.

Die Datei references.bib

Die Datei references.bib ist ein Export aus Zotero Online und enthält einige beispielhafte Literatureinträge. Das Format BibTeX ist dabei austauschbar, pandoc versteht zahlreiche Formate.

@misc{bruch_open_2017,
	title = {Open {Access} auf {Länderebene}},
	url = {https://zenodo.org/record/886347#.XD7Vyp-YVhE},
	abstract = {Open Access auf Länderebene},
	language = {de},
	author = {Bruch, Christoph and Hübner, Andreas and Meinecke, Isabella and Oberländer, Anja and Riesenweber, Christina and Siegert, Olaf},
	month = sep,
	year = {2017},
	doi = {10.5281/zenodo.886347}
}

Für die Zitation einer solchen Quelle im Wiki ist es nun notwendig, [@bruch_open_2017] in den Text einzufügen. Die genauere Syntax für die Zitation mit pandoc-citeproc ist gut dokumentiert. Wir können diesen Code für die Zitation in einer beliebigen Seite des Wikis einfügen.

Eine Wikiseite für die Referenzen

pandoc generiert die Liste der Quellen immer am Ende des Dokuments. Damit dies unter der Überschrift “Referenzen” geschieht, brauchen wir dafür eine neue Wikiseite mit dem Slug referenzen. Sie hat nur eine Zeile # Referenzen gefolgt von einem Zeilenumbruch.⁴

Die Konfigurationsdatei .pandoc-config.yml

An dieser Stelle macht es Sinn, für die wachsende Konfiguration von pandoc eine eigene Datei zu erstellen. Diese kann einen beliebigen Namen tragen, z.B. .pandoc-config.yml. Diese müssen wir in GitLab anlegen und darin das Folgende notieren:

---
title: |
  Ein Buch
subtitle: |
  Kollaboratives Schreiben umfangreicher Dokumente
author:
  - Ein Autorenkollektiv
extratitle: false
lang: de-de
colorlinks: true
links-as-notes: false
papersize: a4
fontsize: 12pt
numbersections: true
toc-depth: 3
lof: true
classoption:
  - oneside
  - headings=small
toc: true
geometry:
  - top=3cm
  - right=3cm
  - left=3cm
  - bottom=3cm
chapters: false
documentclass: scrbook
linestretch: 1.2

# Bibliografie
bibliography: ../references.bib
csl: ../dgp.csl

# Zusätzliche LaTeX-Pakete
header-includes: |
  \usepackage{graphicx}
  \usepackage{csquotes}
  \usepackage{pdflscape}
---

Die verwendeten Direktiven sind in der Dokumentation von pandoc sehr gut beschrieben, daher wollen wir hier nur einige herausgreifen:

• title, subtitle und author werden auf dem Titelblatt erscheinen
• lang sorgt dafür, dass die Internationalisierung und Lokalisierung der Ausgabe funktioniert (“Figure” wird zu “Abbildung” u.ä.)
• colorlinks färbt Links im PDF ein
• links-as-notes macht Links zu Fußnoten
• lof steht für list of figures und fügt ein verlinktes Abbildungsverzeichnis hinter dem Inhaltsverzeichnis ein
• classoption, oneside macht keinen Unterschied zwischen linker und rechter Seite im Buch, twoside schon
• geometry gibt die größe des Seitenrandes an
• documentclass gibt an, dass wir die Wikiseiten als Buch formatieren wollen
• bibliography gibt den Pfad zur Literaturdatei an
• csl steht für Citation Style Language. Es stehen für unterschiedliche Zitationsstile Dateien bei Zotero zur Verfügung, hier wird der Stil der Deutschen Psychologischen Gesellschaft verwendet.
• header-includes gibt verschiedene LaTeX-Pakete an, die den Funktionsumfang noch erweitern. csquotes z.B. beeinflusst den Stil der Anführungszeichen.

Wichtig sind die --- am Anfang und Ende der Datei, weil sie im pandoc-Kontext den so genannten YAML Frontmatter kennzeichnen.

Wenn auf Dateien in der Konfiguration verwiesen wird, müssen diese auch vorhanden sein, sonst erhalten wir in der Pipeline eine Fehlermeldung von pandoc. Das gilt in diesem Fall für die Bibliographie und den Zitationsstil in der CSL-Datei.

Erweiterung der Pipeline-Konfiguration

Damit die zitierte Literatur nun auch berücksichtigt wird, müssen wir die Konfiguration der Pipeline anpassen.

image: xldrkp/pandoc:latest

build:
  before_script:
    - git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@collaborating.tuhh.de/hos/modernes-publizieren/offen/software/konfigurationen/buchprojekt.wiki.git
  script:
    - ls -la
    - cd buchprojekt.wiki
    - ls -la
    - pandoc --version
    - pandoc
        --filter pandoc-citeproc ../.pandoc-config.yml
        einleitung.md
        hintergrund.md
        fazit.md
        referenzen.md
        -o ../buch.pdf
  artifacts:
    paths:
      - "*.pdf"

Neu ist die Zeile, die den Filter pandoc-citeproc und die neue Konfigurationsdatei einbindet. Außerdem integrieren wird noch die neue Datei aus dem Wiki referenzen.md.

Wer das Tutorial nicht mitgebaut hat, kann die zweite Version hier ansehen bzw. herunterladen.

Das CMS komplett machen

Damit wir GitLab auch in diesem Szenario als Content Management System verwenden können, fehlt noch ein letzter Schritt. Bei Änderungen im Wiki soll der Bau des Dokument automatisch angestoßen werden.

Dafür sind zwei weitere Einstellungen zu machen.

Trigger für die Pipeline generieren

Über Settings > CI/CD > Pipeline triggers können wir einen neuen Trigger definieren, z.B. mit dem Namen “Build Book”. Wir erhalten daraufhin ein Token, das wir gleich brauchen.

Unter der Überschrift Use webhook finden wir weiter unten einen Link. Er enthält die Platzhalter REF_NAME und TOKEN. REF_NAME ist mit master zu ersetzen, weil wir nur den master-Branch des Repos bauen. Das Wort TOKEN ersetzen wir durch das neu generierte Token.

Der komplette Link könnte also lauten:

https://collaborating.tuhh.de/api/v4/projects/3051/ref/master/trigger/pipeline?token=08940dafd8f1b4bb55729fffdf18f1

Webhook definieren

Über Settings > Integrations erstellen wir nun einen neuen Webhook, indem wir die URL in das Feld URL ganz oben einfügen. In der Liste der Trigger darunter wählen wir alles außer Wiki Page events ab. SSL verification lassen wir auch aktiviert.

Nach dem Speichern können wir mit dem Button Test ein Wiki-Ereignis triggern. Unter CI/CD > Jobs sollte ein neuer Job gestartet worden sein, der das Label “triggered” trägt.

Test der Automation

Einen letzten Test machen wir, indem wir eine beliebige Wikiseite überarbeiten und wieder unter den Jobs nachschauen, ob das Triggern funktioniert hat.

Aufpassen: Wenn wir eine neue Seite im Wiki anlegen, erscheint diese nicht eher im Buch, bis wir in der .gitlab-ci.yml den entsprechenden Dateinamen aufgenommen haben!

Zugriff auf den jüngsten Build

Neben den Maintainer_innen des Projekts und den Autor_innen mag es in diesem Szenario noch Akteur_innen geben, die lediglich wissen wollen, wie der letzte Stand der Produktion ist. Hierbei hilft ein Badge auf der Landingpage des Projekts, über das die aktuelle Version des generierten PDFs heruntergeladen werden kann.

Es sollte am Kopf der README.md stehen und setzt sich aus einem Badge von shields.io und dem Link zum latest artifact. Dieser kann mithilfe der offiziellen GitLab-Doku gebaut werden. Für unser Beispiel hier lautet er:

[![latest artifact](https://img.shields.io/badge/artifacts-latest-brightgreen.svg)](https://collaborating.tuhh.de/hos/modernes-publizieren/offen/software/konfigurationen/buchprojekt/-/jobs/artifacts/master/raw/buch.pdf?job=build)

Zusammenfassung und Ausblick

Abschließend lässt sich wohl sagen, dass die Einrichtung dieser Entwicklungsumgebung in GitLab einige Erfahrung mit dem System und den beteiligten Komponenten voraussetzt. Für die Autor_innen allerdings ist zunächst lediglich der Umgang mit dem Wiki zu lernen, was unserer Erfahrung nach wesentlich leichter ist als die Arbeit im Hauptrepository.

Mit diesen Einstellungen ist es möglich, kollaborativ an einem umfangreicheren Dokument zu arbeiten. Feinere Einstellungen für das Layout des Buchs sind vorhanden, da pandoc das PDF über LaTeX generiert und dadurch der Layoutgestaltung kaum Grenzen gesetzt sind. Via Ghostscript könnte bspw. der Job dem PDF auch noch ein farbiges Titelblatt hinzufügen. Wir werden hierzu noch einen zweiten Teil des Tutorials nachliefern.

Da in der Pipeline weitere Jobs definiert werden können, sind auch Single-Source-Publishing-Szenarien vorstellbar: Ein anderer Generator könnte z.B. aus den Wikiseiten HTML-Konstrukte bauen und online stellen. Auch hierzu werden wir zukünftig noch veröffentlichen.

Für Lehr-Lernzusammenhänge ist z.B. denkbar, dass Lernende gemeinsam ihre Aufsätze in einem Kompendium zusammenzutragen oder gute Hausarbeiten für eine Veröffentlichung unter CC aufzubereiten.

Der letzte Stand des Beispielprojekts ist unter CC-BY im GitLab der TUHH zum Nachbauen frei verfügbar.

Dank

Vielen Dank an Flo, Tobias und Leif für das Testen des Tutorials und euer qualifiziertes Feedback!