Tutorial Intro

Willkommen in der BSH Common-Doku. Diese Seite ist mit Docusaurus v3 gebaut — einem React-basierten Static-Site-Generator, der speziell für Entwickler-Dokumentationen entwickelt wurde.

Auf dieser Seite findest du:

einen kurzen Crashkurs zur Arbeit mit Docusaurus,
einen Vergleich zu Hugo,
Gründe, warum wir uns für Docusaurus entschieden haben.

Docusaurus in 5 Minuten

Inhalte hinzufügen

Doku-Seiten sind ganz normale Markdown- oder MDX-Dateien unter docs/:

docs/mein-thema.md
---
sidebar_position: 2
---

# Mein Thema

Beliebiger Markdown-Inhalt …

Das Frontmatter steuert Position in der Sidebar, Slug, Titel oder eigene Metadaten. Die Sidebar selbst wird in sidebars.js konfiguriert oder automatisch aus der Ordnerstruktur generiert.

MDX = Markdown + React

Der eigentliche Trumpf: in .mdx-Dateien lassen sich React-Komponenten direkt einbetten.

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="curl" label="cURL">
    ```bash
    curl https://api.bluesafety.dev/health
    ```
  </TabItem>
  <TabItem value="js" label="JavaScript">
    ```js
    await fetch('https://api.bluesafety.dev/health');
    ```
  </TabItem>
</Tabs>

Code-Highlighting & Live-Editor

Codeblöcke unterstützen Syntax-Highlighting, Zeilen-Highlights, Zeilennummern und sogar einen interaktiven Live-Editor.

Live Editor

function Clock() {
  const [date, setDate] = useState(new Date());
  useEffect(() => {
    const id = setInterval(() => setDate(new Date()), 1000);
    return () => clearInterval(id);
  }, []);
  return <h2>Es ist {date.toLocaleTimeString()}.</h2>;
}

Result

Highlight-Direktiven
function highlight(value) {
  if (value) {
    return 'Diese Zeile ist hervorgehoben';
  }
  return 'Nichts hervorgehoben';
}

Lokale Entwicklung

Aus dem Repo-Root:

yarn dev          # Backend + Docusaurus parallel
yarn frontend     # nur die Doku-Site

Hot-Reload aktualisiert Inhalte beim Speichern automatisch im Browser.

Docusaurus vs. Hugo

Hugo ist ein in Go geschriebener, extrem schneller Static-Site-Generator und sehr beliebt für Blogs und Marketing-Seiten. Docusaurus verfolgt einen anderen Ansatz, optimiert auf Developer-Docs.

Aspekt	Docusaurus 3	Hugo
Tech-Stack	React + MDX, Node.js	Go-Templates, einzelnes Go-Binary
Inhalts-Format	Markdown und MDX (React-Komponenten inline)	Markdown + Go-Templates / Shortcodes
Build-Speed	schnell (inkrementell, bis ~10 k Seiten gut)	sehr schnell, skaliert bis zu 100 k+ Seiten
Interaktivität	volle React-App im Browser, Live-Code, State, Routing	reine Static-HTML-Seiten, JS muss man selbst dazubauen
Versionierung	eingebaut (`docs-v1`, `docs-v2`, …)	manuell über Branches/Ordner
i18n	First-Class, in Config + `i18n/`-Ordner	Konfigurations-basiert, gut, aber rudimentärer
API-Referenz	OpenAPI-Plugin generiert komplette Referenz	kein offizielles Plugin, Eigenbau nötig
Suche	Algolia-DocSearch out-of-the-box	externer Service oder Eigenbau (z. B. Lunr.js)
Theming	React-Komponenten-Swizzling, CSS Modules	Go-Templates, partials
Lernkurve	mittel — JS/React-Kenntnisse erleichtern alles	flach für Markdown, steiler bei Go-Template-Logik
Plugin-Ökosystem	npm-Plugins, gepflegt vom Meta-Team	begrenzte offizielle Erweiterungen, viel Konvention
Deployment	statisches Build → GitHub Pages, Vercel, S3 …	identisch — statisches HTML

Wann Hugo glänzt

gigantische Inhalts-Mengen (Blogs mit 50 k+ Posts),
minimale Build-Zeiten ohne Node-Toolchain,
Teams, die schon Go schreiben und keine React-Komponenten brauchen,
klassische Marketing-Seiten oder Personal-Blogs.

Wann Docusaurus glänzt — und warum wir es gewählt haben

Für Developer-Dokumentationen sind das die entscheidenden Vorteile:

MDX statt Shortcodes. Wir können wiederverwendbare React-Komponenten (Tabs, Callouts, API-Beispiele, geschützte Inhalte via AuthGuard) direkt im Markdown nutzen — keine Template-Sprache zu lernen.
OpenAPI-Plugin. Unser Laravel-Backend liefert per Scramble eine OpenAPI-Spec, aus der Docusaurus die komplette API-Referenz generiert (siehe docs/api/). In Hugo wäre das Eigenbau.
Versionierung eingebaut. Mehrere Doku-Versionen parallel zu pflegen (z. B. zur API v1 / v2) ist ein einzelner CLI-Befehl.
i18n First-Class. Deutsche und englische Inhalte teilen sich Sidebar, Routing und Theme — kein Plugin nötig.
Algolia-DocSearch. Volltextsuche mit Tipp-Vorschau ohne eigenen Index-Service.
React-Theming. Wir können einzelne Komponenten gezielt „swizzlen“ (siehe src/theme/) statt eine ganze Template-Hierarchie zu kopieren.
Auth-Layer-Integration. Geschützte Seiten werden client-seitig gegen unser Express-Backend validiert — möglich, weil Docusaurus eine echte React-App ist.

Hugo wäre für eine reine Marketing-Seite die schnellere Wahl. Sobald aber API-Referenzen, Versionierung, Live-Beispiele und interaktive Komponenten zentral sind, spielt Docusaurus seine Stärken aus — und genau das brauchen wir für die BSH-Entwickler-Doku.

Weiter geht's

Docusaurus-Dokumentation
MDX
Hugo — zum Vergleichen und Gegenlesen

Docusaurus in 5 Minuten​

Inhalte hinzufügen​

MDX = Markdown + React​

Code-Highlighting & Live-Editor​

Lokale Entwicklung​

Docusaurus vs. Hugo​

Wann Hugo glänzt​

Wann Docusaurus glänzt — und warum wir es gewählt haben​

Weiter geht's​