Typst im Devcontainer

Ein Textsatzsystem soll den/die Anwender:in unterstützen. Doch oft ist die Einrichtung mit einigen Hürden verbunden. Typst verfolgt hier einen ähnlichen Ansatz wie LaTeX, fühlt sich allerdings in vielen Teilen moderner und schneller an. Development Containers liefern eine einfache Möglichkeit, eine konsistent eingerichtete Umgebung zu haben, und zwar jedes Mal, wenn man das Dokument anfassen muss.

Klingt nach einer guten Kombination, oder?

Grundlagen

Was ist Typst?

Typst ist ein Textssatzsystem ähnlich zu LaTeX, jedoch mit deutlich modernerer Syntax und einer höheren Geschwindigkeit. Man kann damit alles von einfachen Texten über Briefe, Lebensläufe bis hin zu unfangreichen wissenschaftlichen Arbeiten erstellen und sich dabei auf die Inhalte konzentrieren. Die Formatierung übernimmt Typst.

Ich persönlich verwende Typst für formelle Briefe, sowie für meinen Lebenslauf und verschiedene Dokumentationen. Allerdings stoße ich bei komplexen Dokumenten auch immer wieder an Grenzen, und greife dann wieder zu LaTeX. Das mag aber auch an meiner (noch) mangelnden Erfahrung mit Typst liegen.

Einen unschlagbaren Vorteil teilen sich Typst und LaTeX: Da Inhalt und Formatierung strikt voneinander getrennt sind, lässt sich der Inhalt fantastisch versionieren, z. B. mit Git.

Was sind Devcontainer?

Development Containers (kurz: Devcontainers) sind komplette Entwicklungsumgebungen, die alles enthalten, was für Entwicklung und Bau von Softwarekomponenten auf einem bestimmten Technologiestack benötigt wird. Diese Komponenten werden alle in einem oder mehreren Containern bereitgestellt, so dass sie isoliert von anderen Umgebungen sind und damit ausgeschlossen wird, dass man sich mit einer Umgebung eine andere „zerschießen“ kann. Außerdem sind sie über verschiedene Systeme hinweg konsistent und in der Regel unabhängig vom Betriebssystem. Mit ein wenig Aufwand lässt sich sogar eine IDE einbetten (z. B. ein webbasiertes Visual Studio Code).

Außerdem lassen sich mit Devcontainern auf einfache Weise Umgebungen in Pipelines und für Testläufe bereitstellen.

Für die Nutzung von Devcontainern benötigt man Docker oder ähnliches. DevPods arbeiten nach dem gleichen Muster und verwenden identische Konfiguration. Über DevPod muss ich an anderer Stelle mich nochmal mehr auslassen.

Projektstruktur

Neben den eigentlichen Quelldateien des Dokuments muss noch die Konfiguration des Devcontainers ihren Platz finden. Ich verwende dabei dieses Strukturschema (am Beispiel für Bewerbungsunterlagen):

1Bewerbungsunterlagen/
2├─ .devcontainer/
3│  ├─ devcontainer.json
4│  ├─ Dockerfile
5├─ .gitignore
6├─ Anschreiben.typ
7├─ Lebenslauf.typ
8├─ README.md

Neben zwei Typst-Dateien (Anschreiben.typ und Lebenslauf.typ) sehen wir im Projekthauptverzeichnis eine Datei .gitignore, die jene Dateien oder Wildcards auf Dateien enthält, die nicht mit eingecheckt werden sollen (z. B. PDF-Dateien). Außerdem ist es guter Stil, jedes Repository mit einer README.md einzuleiten, die kurz beschreibt, um was es hier geht. Auch bei rein privaten Repos kann dass von Vorteil sein. Hier ist dann auch Platz für das Beschreiben von Besonderheiten beim Bau des Projekts.

Doch hier soll es sich hauptsächlich um den Ordner .devcontainer drehen. Hier ist alles enthalten, was wir für den Aufbau und die Verwendung eines Development Containers brauchen.

Konfiguration eines Containers

Die Grundkonfiguration findet sich in der Datei .devcontainer/devcontainer.json. Wir brauchen nur wenige Einstellungen, darunter einen Namen für unser Projekt, einer Liste von Erweiterungen für Visual Studio Code, und einem Verweis auf ein Dockerfile, welches die eigentliche Entwicklungsumgebung beschreibt:

 1{
 2    "name": "Bewerbungsunterlagen",
 3    "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
 4    "customizations": {
 5        "vscode": {
 6            "extensions": [
 7                "nvarner.typst-lsp",
 8                "tomoki1207.pdf"
 9            ]
10        }
11    },
12    "build": {
13        "dockerfile": "Dockerfile"
14    }
15}

Die Angabe unter workspaceFolder zeigt an, an welcher Stelle im Container wir unseren »Code« (also in diesem Fall unsere .typ-Dateien) bearbeiten wollen. Ich verwende hier eigentlich in jedem Devcontainer die Standard-Angabe /workspaces/${localWorkspaceFolderBasename}. Für die Verwendung mit Typst reichen mir zwei Eweiterungen für Visual Studio Code, nämlich ein PDF-Viewer (tomoki1207.pdf) und eine Typst-Erweiterung für Syntax-Highlighting und Co. (nvarner.typst-lsp).

Mehr Informationen über alle Konfigurationsmöglichkeiten gibt es hier: Development Containers Specification.

Der Aufbau des eigentlichen Containers findet im Dockerfile statt.

Als Basis für die Verwendung von Typst wird uns Alpine Linux dienen. Es ist besonders kompakt und bringt alles mit, was wir für die Nutzung von aktuellen Typst-Versionen brauchen. Jedoch benötigt das Basis-Image ein paar kleinere Anpassungen, insbesondere fehlen Schriftarten und einige wenige Tools.

Unser Dockerfile wird so aussehen:

 1FROM alpine:latest AS fontBuilder
 2
 3RUN apk add wget unzip
 4RUN (mkdir -p /work && cd /work && wget -O ss3.zip 'https://github.com/adobe-fonts/source-sans/releases/download/3.052R/OTF-source-sans-3.052R.zip')
 5RUN (cd /work && unzip ss3.zip)
 6
 7FROM alpine:latest
 8
 9LABEL org.opencontainers.image.authors="Juergen Edelbluth <****@********.***>"
10
11RUN apk update && apk upgrade
12RUN apk add font-terminus font-inconsolata font-dejavu font-noto font-noto-cjk font-noto-extra font-noto-music font-noto-signwriting font-noto-emoji font-awesome font-noto-extra font-droid font-croscore font-bitstream-type1
13RUN apk add font-adobe-utopia-100dpi font-bitstream-100dpi font-freefont font-vollkorn font-overpass font-dejavu font-liberation font-linux-libertine font-opensans font-unifont font-awesome
14RUN apk add msttcorefonts-installer fontconfig
15
16RUN update-ms-fonts
17
18RUN mkdir -p /usr/local/share/fonts
19COPY --from=fontBuilder /work/**/*.otf /usr/local/share/fonts
20
21RUN fc-cache -f
22
23RUN apk add git gpg wget curl bash bash-completion shadow nano starship openssh-client openssh-sftp-server
24RUN chsh -s /bin/bash
25RUN echo 'eval "$(starship init bash)"' >> ~/.bashrc
26
27RUN apk add typst typst-bash-completion typst-doc

Aber der Reihe nach.

In einem ersten Schritt besorgen wir uns noch eine Schriftart (Adobe Source Sans), die nicht in den Repositories von Alpine Linux verfügbar ist. Dazu nutzen wir auch Alpine Linux, eben weil es so schön schlank ist. In den Zeilen 1-5 laden wir also die gewünschte Schriftart herunter und entpacken die heruntergeladene Datei in einen Arbeitsordner. Auf diesen Ordner nehmen wir später wieder Bezug (Zeile 19).

Damit geht es jetzt direkt mit dem Bau des eigentlichen Containers weiter.

Zunächst aktualisieren wir alle bereits installierten Pakete (Zeile 11), bevor in den Zeilen 12 und 13 weitere Schriftarten aus den Repositories von Alpine Linux. Ergänzt wird die Schriftarteninstallation in Zeile 14 durch die Bereitstellung des Downloaders für Microsoft Standard-Schriftarten und dem Tool fontconfig. Zeile 16 nutzt nun den Dwonloader aus Zeile 14. In Zeile 18 stellen wir sicher, dass der Zielordner für die in den Zeilen 1-5 heruntergeladenen Schriften existiert, bevor diese in Zeile 19 dorthin kopiert werden. Zeile 21 führt das fontconfig-Tool aus und schließt damit die Installation der Schriftarten ab.

Die Zeile 23 installiert weitere wichtige Tools und einige Dinge, die die Entwicklung erleichtern. Unter anderem die Bash-Shell und Starship, welches ein besseres Bash-Prompt bereitstellt. In Zeile 24 wird Bash dann als Standard-Shell eingestellt und das Laden der Starship-Konfiguration in die .bashrc ermöglicht.

Zeile 27 schließt die Einrichtung des Containers mit der Installation von Typst ab.

Verwendung des Devcontainers

Öffnet man den Projektorder Bewerbungsunterlagen nun in Visual Studio Code und hat das Devcontainer-Plugin von Microsoft installiert, bietet VS Code gleich an, das Projekt im Container zu öffnen. Bestätigt man dies, arbeitet man wenige Sekunden später im Container und kann im VS Code Terminal mit dem Befehl typst w Lebenslauf.typ den Lebenslauf aus dem Beispiel kompilieren. Ein Doppelklick auf die passende PDF-Datei öffnet die Vorschau.