Zum Hauptinhalt springen

Zusatzfunktionen

Hinweis

Die auf dieser Seite beschriebenen Zusatzfunktionen erfordern zum Teil grundlegende Programmierkenntnisse. Die Seite wendet sich daher primär an eine entsprechende Zielgruppe.

Dennoch ist es für alle an der Dokumentationserstellung beteiligten Personen empfehlenswert, sich einen Überblick der hier beschriebenen vorhandenen/verfügbaren Funktionen zu verschaffen.

Diese Seite dokumentiert zusätzliche Funktionen (Plugins und React-Komponenten), die speziell für Dokumentationswebsites entwickelt wurden und die Arbeit deutlich erleichtern. Da diese bereits im Template-Repository (öffnet in neuem Tab) integriert sind, stehen sie Ihnen als Autor:in sofort zur Verfügung - ohne dass Sie selbst Installationsschritte durchführen müssen.
Darüber hinaus finden Sie auf dieser Seite auch Beschreibungen zu weiteren projektspezifisch umgesetzte Lösungen, die nicht im Template-Repository enthalten sind.

Glossar (optional)​

Die Dokumentation kann durch ein automatisch erstelltes Glossar ergänzt werden. Hierzu wurde das docusaurus/terminology Plugin eingebunden. Das Plugin erstellt eine verlinkte Liste aus einzelnen Begriffen und ergänzt automatisch Links und Schnellinformationen (per Tooltip) in den jeweiligen Dokumenten. Dazu muss eine bestimmte Struktur eingehalten werden.

Begriff erstellen​

Damit die automatische Erstellung funktioniert, sollte jeder Glossar-Begriff sein eigenes .md(x) Dokument im ./docs/terms Verzeichnis haben. Die Struktur ist wie folgt:

---
id: term_name
title: Titel der Seite
hoverText: Eine Kurzbeschreibung des Begriffs, wird bei Mouse-Over angezeigt.
---

### Begriff

Ausführliche inhaltliche Beschreibung folgt hier...

Achtung: Die hoverText und id Attribute werden zwingend benötigt. Es bietet sich an das Dokument nach term_name zu benennen.

Verwendung von Mustern zur Referenzierung​

Um einen Glossar-Begriff in einem anderen docs/*.md(x) Dokument zu referenzieren, wird folgendes Muster verwendet:

%%term_text|term_name%%

wobei:

  • term_text: Der Begriffs-Text der in der Dokumentationsseite sichtbar sein soll.
  • term_name: Der Wert des eindeutigen id Attribut, das im .md(x) des Begriffs verwendet wird.

Beispiel​

Nehmen wir an in ./docs/terms/chocolate.md ist ein Begriff mit id: chocolate definiert. Der Begriff kann von jeder Seite der Dokumentation aus wie folgt referenziert werden:

Viele Leute fragen sich, wie %%Schokolade|chocolate%% eigentlich hergestellt wird...

Das Plugin wird das Muster mit diesem Inhalt ersetzen:

Viele Leute fragen sich, wie <Term reference="chocolate" popup="Kurzbeschreibung von Schokolade aus der Datei chocolate.md">Schokolade</Term> eigentlich hergestellt wird...

Die <Term> React-Komponente enthält dann den Link zum Glossar und eine Tooltip-Funktionalität.

Achtung: Das Script sollte nicht lokal ausgeführt werden, da es die Markdown-Dokumente verändert. Diese Änderungen sollten nie ins Git gelangen, sonst funktioniert die Mustererkennung bei zukünftigen Veränderungen nicht mehr.

Lokales Testen der Änderungen​

Wichtiger Hinweis

Um die nachfolgend beschriebene Funktion zu nutzen, benötigen Sie eine lokale Git-Installation auf Ihrem Computer und ein Terminal.

Wenn die Begriffe und Muster in .md Dateien angelegt sind, kann lokal das Plugin im dry-run Modus ausgeführt werden. So werden mögliche Kompilierungsfehler angezeigt und eine Beispiel-Ausgabe aller Änderungen, die das Plugin vornehmen würde:

yarn docusaurus parse --dry-run

Hinweis: Aufgrund eines Bugs im Plugin kann es auf Windows-Systemen vorkommen, dass das lokale ausführen einen Fehler ⚠ No term files found wirft. Dies kann umgangen werden indem man das Linux Subsystem nutzt und dort entwickelt.

Mögliche Probleme bei der Einbindung​

  • Das docusaurus/terminology Plugin funktioniert momentan nur einwandfrei in Dokumenten, die über ein Front Matter verfügen!

    Lösung: in betroffenen Dateien ein Front Matter ergänzen.

    ---
    id: Meine Seite
    ---

  • Je nach Konfiguration des Routings können evtl. die Links auf die Begriffe nicht funktionieren, Grund ist ein Bug im Plugin.

    Lösung: den Docusaurus Config-Parameter routeBasePath auf 'docs' setzen (Standard, wenn Sie das Template-Repository verwenden).

  • Nach obiger Änderung kann es zu einem Fehler beim Build-Vorgang, besser gesagt bei der anschließenden Prüfung der Links kommen.

    Lösung: Prüfen ob eine Startseite für die / Route vorhanden ist (z.B. src/pages/index.mdx). Diese kann auch einfach nur einen Redirect auf die Startseite der Dokumentation unter docs/ enthalten.

  • Die automatisch erstellte Glossar-Seite erscheint nicht in der Sidebar.

    Lösung: Die Vorlage des glossary.md muss einen title enthalten. Das Template-Repository enthält eine Referenz-Implementierung.

Erzeugung der Glossar-Docs in der CI​

Da das Glossar-Plugin Markdown-Dateien verändert, sollen diese veränderten Dateien nie ins Git gelangen. Stattdessen sollte lokal nur mit dem dry-run Modus getestet werden und die eigentliche Erzeugung des Glossars in der Gitlab-Ci stattfinden.

Dazu wurden folgende Schritte in der Gitlab-CI hinzugefügt:

...
build:
  ...
  script:
    - ...
    - yarn docusaurus parse
    - yarn docusaurus glossary
    - yarn build
  ...

Duale Suche (Suche im FEP)​

Diese Funktion ermöglicht ein Umschalten der Suche zwischen "Suche in lokaler Dokumentationswebsite" und "Suche im Föderalen Entwicklungsportal (FEP)".
Die duale Suche ist per Default deaktiviert. Sie kann in der Datei .gitlab-ci-variables.yml mit der Variablen SEARCH_IN_FEP aktiviert werden.

Nähere Informationen zu dieser Funktion im Wiki des Föderalen Entwicklungsportals (öffnet in neuem Tab).

Erstellen von Diagrammen mit Mermaid​

Mermaid-Diagramme sind code-basierte Diagramme, die direkt aus Text generiert werden, sodass keine zeitaufwändigen Design-Tools erforderlich sind.
Diagramme können mit Mermaid.js (öffnet in neuem Tab) direkt in der Dokumentation erstellt werden. Dazu legt man einfach in einem Markdown-Dokument einen Code Block mit mermaid als Sprache an:

```mermaid
  sequenceDiagram

  # Participants
  participant A as Alice
  participant B as Bob

  # Relations
  A ->> B: Hi Bob!
  B ->> A: Nice to meet you, Alice
```

Im Ergebnis werden die obigen Zeilen dann so gerendert:


Hinweis

Das dargestellte Sequenzdiagramm dient lediglich als simples Beispiel.
Mermaid unterstützt zahlreiche Diagrammtypen, darunter Fluß-, Klassen-, Zustands-, GANTT-, Tortendiagramme, Mindmaps, Zeitleisten, usw.

Verfügbare React-Komponenten und ihre Verwendung​

Docusaurus bietet integrierte Unterstützung für MDX, wodurch Sie JSX in Ihren Markdown-Dateien schreiben und als React-Komponenten rendern können.

Weitere Informationen zu MDX

Weitere Informationen zu MDX finden Sie in der Docusaurus Online Dokumentation (öffnet in neuem Tab) und auf mdxjs.com (öffnet in neuem Tab).

Dabei sind zwei Fälle zu unterscheiden:

  • Installierte Pakete
    Einige Pakete sind bereits installiert, weil sie von den im Template-Repository enthaltenen Funktionen genutzt werden. Diese Pakete können Sie bei Bedarf auch in eigenen MDX-Dateien verwenden.
  • Mitgelieferte Komponenten
    Zusätzlich enthält das Template-Repository React-Komponenten (z. B. unter src/components), die Sie in MDX importieren und nutzen können.

Installierte Pakete importieren Sie direkt aus node_modules (z. B. @tabler/icons-react). Mitgelieferte Komponenten importieren Sie aus @site/src/components/....

Tabler Icons​

Tabler Icons ist eine Open-Source-Icon-Sammlung, die als SVGs und (für React) als fertige Komponenten verfügbar ist. Hier finden Sie eine Übersicht aller Icons (öffnet in neuem Tab).

Da @tabler/icons-react im Template bereits installiert ist, können die Icons direkt in MDX-Dateien (oder .md-Dokumenten mit MDX-Unterstützung) genutzt werden:

import { IconAlertTriangle } from '@tabler/icons-react'

Beispiel als „großes“ Icon:

<IconAlertTriangle size={48} stroke={1.5} />
Achtung

Achtung

Beispiel inline im Fließtext:

Man kann Icons auch inline benutzen: <IconAlertTriangle size={16} />, also innerhalb von Text.

Man kann Icons auch inline benutzen: , also innerhalb von Text.

Damit die Inline-Verwendung nicht ungewollt einen Zeilenumbruch erzwingt, muss die CSS-Regel für Tabler-SVGs in src/css/custom.scss vorhanden sein:

.markdown svg.tabler-icon {
  display: inline-block;
  vertical-align: -0.125em
}

Docusaurus Hook useBaseUrl()​

useBaseUrl() ist sinnvoll, sobald Sie URLs zu statischen Ressourcen oder internen Pfaden in JSX/React schreiben (z. B. in MDX-Komponenten) und die Website nicht am Domain-Root (/) ausgeliefert wird. Das ist typisch für Deployments unter einem Unterpfad (z. B. https://example.org/docs/) oder in Preview-Umgebungen.

Mit useBaseUrl() werden Pfade wie /img/logo.svg oder /files/handbuch.pdf automatisch mit dem in der Docusaurus-Konfiguration gesetzten baseUrl kombiniert, sodass Links und src-Attribute auch unter Unterpfaden korrekt funktionieren.

Beispiel:

import useBaseUrl from '@docusaurus/useBaseUrl'

function HandbuchDownload() {
  const href = useBaseUrl('/files/handbuch.pdf')

  return <a href={href}>Handbuch herunterladen</a>
}

<HandbuchDownload />

ApiLink (src/components/ApiLink.js) erzeugt stabile Verweise auf einzelne Operationen in der API-Spezifikation unter /docs/spec. Übergib per to den Pfad (Platzhalter wie {id} werden dabei automatisch in gültige Fragment-IDs verwandelt) und optional withMethod, damit die verlinkte Überschrift aus get, post etc. besteht.

import ApiLink from '@site/src/components/ApiLink'

<ApiLink to="/pets" withMethod="post" />
<ApiLink to="/pets/{id}">Details zur Operation anzeigen</ApiLink>

Ohne children rendert die Komponente automatisch einen Inline-Codeblock wie POST /pets. Sobald children gesetzt sind, wird deren Inhalt als Linktext verwendet.

Hinweis: Wenn Sie diese Komponente in Verbindung mit einer externen URL verwenden, denken Sie bitte daran, die externe Domain in der Datei static/.htaccess zu den CSP-Regeln hinzuzufügen (Regel connect-src).

ApiSpec​

ApiSpec (src/components/ApiSpec.js) bindet RapiDoc (öffnet in neuem Tab) innerhalb eines BrowserOnly-Wrappers ein. Damit bleibt der Build serverseitig stabil und die API-Dokumentation erscheint nur im Browser. Übergeben Sie per specUrl die gewünschte OpenAPI-Quelle; relative Pfade (z. B. /spec/petstore.yaml) werden automatisch via useBaseUrl aufgelöst, externe URLs erwartungsgemäß unverändert verwendet.
Unabhängig davon stellt die Komponente immer auch einen Download-Link zur gleichen Ressource bereit.

import ApiSpec from '@site/src/components/ApiSpec'

<ApiSpec specUrl="/spec/petstore.yaml" />

Weitere Props sind nicht erforderlich: Layout, Farbgebung, deaktivierte try it out-Funktion sowie der lesende Modus sind projektweit festgelegt.

Hinweis: Wenn Sie diese Komponente in Verbindung mit einer externen URL verwenden, denken Sie bitte daran, die externe Domain in der Datei static/.htaccess zu den CSP-Regeln hinzuzufügen (Regel connect-src).

Subscribe: E-Mail-Abos sammeln​

Subscribe (src/components/Subscribe.js) stellt ein kompaktes Formular bereit, um E-Mail-Abos einzusammeln. Die Komponente sendet fullname und email per POST an die über formPostUrl konfigurierte Zieladresse und blendet die enthaltenen children nach erfolgreicher Übermittlung oder nach Klick auf „Nicht abonnieren“ ein (z. B. manuelle Download-Links als Alternative).

import Subscribe from '@site/src/components/Subscribe'

<Subscribe formPostUrl="https://example.org/newsletter">
  <p>Direkt herunterladen? Dann findest du die Unterlagen unter den folgenden Links...</p>
</Subscribe>

Die CSS-Klasse subscribe-form ist bereits in src/css/custom.scss gestaltet, daher keine zusätzlichen Wrapper oder Inline-Styles ergänzen.

Weitere projektspezifisch umgesetzte Lösungen​

Neben den beschriebenen und im Template-Repository enthaltenen Funktionen und Komponenten gibt es projektspezifische Lösungen, die bereits erfolgreich im praktischen Einsatz sind. Diese können als Inspiration oder Ausgangspunkt für eigene Implementierungen dienen.

Konvertierung von Markdown zu PDF​

Obwohl Dokumentationswebsites zahlreiche Vorteile bieten, gibt es in der öffentlichen Verwaltung weiterhin legitime Anwendungsfälle für PDF-Dokumente:

  • Gremienvorlagen: Für Ausschusssitzungen, Beschlussvorlagen oder Kabinettssitzungen werden häufig druckbare, versionierte Dokumente benötigt, die einen definierten Stand abbilden.
  • Offline-Nutzung: Bei Vor-Ort-Terminen, Schulungen oder in Bereichen mit eingeschränktem Internetzugang sind offline verfügbare Dokumente unerlässlich.
  • Formelle Übergaben: Bei Abnahmen, Vertragsunterlagen oder der Übergabe an externe Stakeholder wird oft ein „eingefrorener" Dokumentenstand erwartet.
  • Veröffentlichungspflichten: Manche Dokumente müssen in einem Format bereitgestellt werden, das unverändert zitierbar und referenzierbar ist – etwa technische Spezifikationen oder Richtlinien.
  • Druckversionen für Schulungen: Teilnehmende an Workshops oder Schulungen erhalten oft gedruckte Handouts zur Mitnahme.
  • Veraktungspflicht: PDFs sind geeignet, um definierte Zwischenstände der Dokumente für die Ablage in der E-Akte zu erstellen.

PDF und Web-Dokumentation sind dabei keine Gegensätze, sondern ergänzen sich. Wer tiefer in die jeweiligen Stärken und Schwächen einsteigen möchte, findet nachfolgend eine entsprechende Gegenüberstellung.

Gegenüberstellung „PDF-Dokumente vs. Dokumentationswebsite"
KriteriumPDFDokumentationswebsite
AktualitätDefinierter Versionsstand, ideal für Snapshots und Archivierung.Sofortige Updates möglich (automatisierte Deployments).
Offline-VerfügbarkeitVollständig offline nutzbar, keine Internetverbindung erforderlich.Grundsätzlich Internetzugang erforderlich (Ausnahme: PWA-Funktionen).
DruckbarkeitOptimiertes Drucklayout, konsistente Seitenumbrüche und Formatierung.Druckansicht oft suboptimal, Layout kann variieren.
ZitierfähigkeitStabile Seitenzahlen, eindeutig referenzierbar.URLs können sich ändern, keine festen Seitenzahlen.
WeitergabeEinfach als einzelne Datei per E-Mail oder Datenträger verteilbar.Link-Weitergabe setzt Internetzugang beim Empfänger voraus.
RechtsverbindlichkeitEtabliert für Verträge, Bescheide und formelle Dokumente; digital signierbar.Weniger etabliert für rechtsverbindliche Zwecke.
BarrierefreiheitUmsetzung möglich (PDF/UA), aber oft vernachlässigt.Einfacher umsetzbar (WCAG-konform, Screenreader-freundlich).
DurchsuchbarkeitNur innerhalb des einzelnen Dokuments.Volltextsuche über die gesamte Dokumentation.
NutzerfreundlichkeitKonsistentes Layout, gut für lineares Lesen.Responsive, interaktiv (Verlinkungen, Videos, Tabellen).
KollaborationEinzelbearbeitung, Versionen schwer nachvollziehbar.Mehrere Autor:innen, Versionierung (Git), Review-Prozesse.
IntegrationEinbettung in DMS und E-Akte etabliert.API-Anbindung, Einbettung in Portale, KI-Tools.
AnalyticsKeine Nutzungsdaten (außer Download-Statistiken).Detaillierte Statistiken (Besucherzahlen, Absprungraten, Suchbegriffe).
SicherheitVerschlüsselung und Passwortschutz möglich; etabliert für vertrauliche Dokumente.Granulare Berechtigungen, Audit-Logs, HTTPS-Verschlüsselung.
KostenKeine Hosting-Kosten für die Datei selbst.Geringere Betriebskosten bei Massenverteilung, weniger Supportanfragen.
ZukunftssicherheitPDF/A ist ISO-Standard für Langzeitarchivierung.Offene Standards (HTML, Markdown), einfache Migration.
Onboarding & SchulungGut für lineare, abgeschlossene Lerneinheiten.Interaktive Tutorials, Videos, Schritt-für-Schritt-Anleitungen.
BürgerfreundlichkeitVertrautes Format, kein Navigieren auf Websites nötig.Direkter Zugriff, auffindbar über Suchmaschinen, verlinkt mit anderen Diensten.
LanglebigkeitPDF/A ist für Langzeitarchivierung konzipiert.Abhängig von Hosting und Pflege der Website.
MultilingualitätKlare Sprachversionen in separaten Dateien.Einfache Verwaltung mehrerer Sprachen in einem System (z. B. über Plugins).

Der empfohlene Ansatz: Markdown als Single Source of Truth nutzen und daraus beide Formate generieren – so profitieren Sie von den Vorteilen der Web-Dokumentation, ohne auf PDFs verzichten zu müssen, wenn diese benötigt werden.

Diese Funktionalität ist im Projekt DVC Docs im praktischen Einsatz und ermöglicht die Generierung druckfertiger Dokumentationen aus Markdown-Quellen.

Die Implementierung basiert auf einer erweiterten Gitlab-CI-Pipeline, die Pandoc (öffnet in neuem Tab) verwendet, um – zusätzlich zur üblichen HTML-Ausgabe – PDF-Dokumente aus allen oder einzelnen vorhandenen Markdown-Dateien zu generieren. Bei Bedarf können auch mehrere Markdown-Dateien zu einem PDF-Dokument zusammengefasst werden.

Eine detaillierte Beschreibung der Implementierung findet sich im Wiki des Projekts (öffnet in neuem Tab).

Nachnutzung

Die Lösung kann als Ausgangspunkt für eigene PDF-Generierungsworkflows dienen. Anpassungen am Styling können entsprechend dem Bedarf vorgenommen werden.