Docs as Code
Zwei Arten, eine Website zu betreiben
Abschnitt betitelt „Zwei Arten, eine Website zu betreiben“Ein Content-Management-System wie WordPress oder Moodle speichert Inhalte in einer Datenbank und baut jede Seite beim Aufruf neu zusammen. Dafür braucht es auf dem Server eine Programmiersprache, eine Datenbank, Updates, Backups der Datenbank und Schutz vor Angriffen auf die Login-Maske.
Eine statische Website besteht nur aus fertigen HTML-, CSS- und JavaScript-Dateien. Der Webserver liefert sie aus, mehr nicht. Es gibt nichts, das gehackt werden könnte, ausser dem Webserver selbst. Backups sind trivial, weil die Quelle in Git liegt.
flowchart LR
A[Markdown in Git] -->|npm run build| B[dist/ mit HTML, CSS, JS]
B -->|rsync| C[Webserver]
C --> D[Browser]
«Docs as Code» heisst: Inhalte werden behandelt wie Programmcode. Sie liegen als Textdateien im Repository, Änderungen laufen über Branches und Merge Requests, eine Pipeline prüft und veröffentlicht. Genau so arbeiten Software-Teams mit ihrer Dokumentation, und genau so entsteht diese Plattform.
| Statische Seite | CMS | |
|---|---|---|
| Inhalte ändern | Textdatei, Git, Pipeline | Web-Oberfläche |
| Server | Nur Webserver | Webserver, PHP oder ähnlich, Datenbank |
| Sicherheit | Kaum Angriffsfläche | Regelmässige Updates nötig |
| Nachvollziehbarkeit | Jede Änderung ein Commit | Je nach System |
| Gut für | Dokumentation, Kurse, Blogs | Shops, Portale mit Logins, viele Redaktoren ohne Git |
Generatoren
Abschnitt betitelt „Generatoren“Statische Seiten schreibt niemand von Hand. Ein Static Site Generator nimmt Markdown-Dateien und eine Konfiguration und erzeugt daraus die HTML-Dateien. Bekannte Vertreter:
- MkDocs mit dem Theme Material: Python, sehr verbreitet für technische Doku, schnell eingerichtet.
- Docusaurus: React, von Meta, flexibel, aber schwergewichtig.
- Hugo: Go, extrem schnell, eigene Template-Sprache.
- Astro Starlight: Astro-Framework, moderne Komponenten, Suche und Dark Mode eingebaut.
Für diese Plattform fiel die Wahl auf Starlight. Die Gründe: Die Sidebar, die Volltextsuche (Pagefind), Dark Mode und Komponenten wie Tabs oder Schritte sind dabei. Eigene Komponenten lassen sich mit wenig Code bauen, das Quiz auf dieser Seite ist eine davon. Und das Ergebnis ist eine reine statische Seite ohne Laufzeitabhängigkeiten.
Wie Astro arbeitet
Abschnitt betitelt „Wie Astro arbeitet“Astro ist ein Web-Framework, das standardmässig kein JavaScript an den Browser schickt. Komponenten laufen beim Build und erzeugen HTML. Nur wo du es ausdrücklich willst, zum Beispiel beim Quiz-Button, landet ein kleines Skript auf der Seite. Starlight ist ein Aufsatz auf Astro, der alles mitbringt, was Dokumentation braucht.
Die Dateien, mit denen du arbeiten wirst:
| Datei oder Ordner | Zweck |
|---|---|
src/content/docs/ |
Deine Inhalte, Markdown und MDX. Jede Datei wird eine Seite. |
astro.config.mjs |
Konfiguration: Titel, Sidebar, Plugins. |
src/components/ |
Eigene Komponenten. |
src/styles/ |
Eigenes CSS. |
public/ |
Dateien, die unverändert kopiert werden: Favicon, .htaccess. |
dist/ |
Das Ergebnis des Builds. Wird nie committet. |
Selbstcheck · 3 Fragen