Anleitung zur Inhaltsbearbeitung

Zusammenfassung

Hier finden Sie Hilfestellungen rund um die Gestaltung Ihrer Dokumentationswebsite und den Umgang mit Markdown in Zusammenhang mit Docusaurus im Föderalen Entwicklungsportal.

Navigation

Eine Dokumentationswebsite besteht aus vielen Einzelseiten, die – ähnlich wie eine Akte – in Abschnitte und Unterabschnitte gegliedert sind. Damit Nutzer:innen sich stets orientieren und gezielt die benötigten Inhalte finden, stellt Docusaurus spezielle Navigationshilfen bereit. Dieser Abschnitt erklärt die wichtigsten dieser vordefinierten Elemente.

Erklärtext zur Infografik

• Navbar (oben): Wechsel zwischen Hauptbereichen, ggf. mit Dropdown-Menüs
• Sidebar (links): Navigation innerhalb eines Bereichs, meist als Inhaltsbaum
• On-Page-Navigation (rechts): Sprungmarken innerhalb der aktuellen Seite (Überschriften)

Docusaurus unterstützt sowohl eine horizontale Navigationsleiste (Navbar, oben im Bild), bei Bedarf mit Dropdown-Elementen, als auch eine Navigation über eine Seitenleiste (Sidebar, links im Bild zu sehen).

Zusätzlich befindet sich auf jeder Seite eine Sekundäre On-Page-Navigation entsprechend der Überschriftenstruktur auf der jeweiligen Seite (rechts zu sehen), welche über entsprechende Parameter im Header der Markdowndatei modifiziert oder auch ganz ausgeblendet werden kann.

tipp

Überlegen Sie sich zuerst eine sinnvolle Struktur für Ihr Informationsangebot in Form eines Navigationsbaums. Hilfreich ist dazu die Verwendung einer Tabelle (oder eines Outline-Editors oder eine MindMap). Die Spalten stellen dann die Navigationsebene dar. Verwenden Sie in der horizontalen Navigationsleiste (sofern Sie diese verwenden) ebenso wie in der Seitenleiste nicht mehr als drei Ebenen, keinesfalls mehr als vier: Von vielen Nutzenden werden mehr als drei oder vier Ebenen als "zu komplex" empfunden.
Die meisten Dokumentationswebsites lassen sich bereits mit einer einfachen vertikalen Seitenleiste und maximal zwei Navigationsebenen übersichtlich strukturieren.

Aus dem Navigationsbaum ergeben sich die einzelnen Seiten/Markdown-Dokumente.

Horizontales Navigationsmenü (Navbar)

Navigationselemente werden in der Datei docusaurus.config.js unter themeConfig > navbar konfiguriert. Einzelheiten zur Konfiguration der Navbar sind auf dieser Seite (öffnet in neuem Tab) beschrieben.

Seitenleiste (Sidebar)

Auch die Seitenleiste kann zu Navigationszwecken verwendet werden (in der Praxis ist das die am häufigsten verwendete Navigation).
Die Struktur der Seitenleiste wird in der Datei sidebar.js festgelegt. Dort können Sie:

• Inhalte nach Themen gruppieren
• Seiten über ihre Slugs oder Document-IDs verknüpfen
• Die Anzeige auf bestimmte Seiten beschränken (nur Seiten, die in der Navigation definiert sind, zeigen die Leiste an)

Weitere Informationen sind in der Docusaurus-Dokumentation (öffnet in neuem Tab) zu finden.

Ablagestruktur

Docusaurus erwartet eine bestimmte Verzeichnisstruktur. Diese ist einzuhalten, um Build-Fehler zu vermeiden.

Dokumente

Alle Inhaltsdokumente werden im Ordner docs des Repository-Root-Verzeichnisses abgelegt. Die Strukturierung (Anzahl und Namen der Dateien, sowie Unterverzeichnisse) innerhalb des docs-Ordners kann wiederum nach konkreten Bedarfen angelegt werden.

Hinweis

Die Ablagestruktur muss nicht zwingend der Darstellung und Struktur des Navigationsbaums entsprechen: Letzterer kann individuell über die Datei sidebar.js konfiguriert werden.
Weitere Informationen dazu finden Sie in der Docusaurus-Dokumentation (öffnet in neuem Tab).

Bilder

Es gibt zwei gängige Wege, Bilder in Docusaurus abzulegen:

1. Globaler Ordner (static/images): Bilder, die an vielen Stellen benötigt werden oder eine feste, öffentliche URL haben sollen, gehören in den Ordner static/images (Unterordner sind möglich). Diese Bilder sind später unter ihrem exakten Dateipfad erreichbar (allerdings ohne static/).

2. Nah beim Dokument (Colocation): Bilder, die nur zu einem bestimmten Artikel gehören, können direkt im selben Verzeichnis wie die Markdown-Datei (oder einem Unterordner davon, z. B. images) gespeichert werden. Der Unterschied: Diese Bilder werden vom System verarbeitet und erhalten beim Bauen der Webseite automatisch generierte Dateinamen. Sie eignen sich daher nicht für externe Verlinkungen, halten aber die Ordnerstruktur sauber, da Bild und Text zusammenbleiben.

Dateinamen

Dateinamen sollten sprechend sein und das behandelte Thema oder dargestellte Bild mit 1-2 Worten benennen. Zur besseren Sortierung können Ordner verwendet werden.

Dateinamen sollten nicht die Struktur der Veröffentlichung vorgeben, da diese sich durch Änderungen während der Arbeit oder durch Weiterentwicklungen des dokumentierten Gegenstands ändern kann.

Beispiel:

• Statt 01-einleitung-07-siebter-Abschnitt-ueber-wasserkocher.md besser wasserkocher.md

Statt Leerzeichen sind Bindestriche zu verwenden, falls eine Trennung erforderlich ist.

Beispiele:

• Einleitung.md
• Anleitung-zur-Nutzung.md

Umlaute und andere Sonderzeichen sind zu vermeiden.

Beispiel:

• Statt inhaltsübersicht.md besser inhaltsuebersicht.md

Markdown-Dateien

Header (Front Matter)

In Markdown-Dateien kann ein Header (Fachausdruck: Front Matter) enthalten sein, der beispielhaft wie folgt aussieht:

Dabei kann die ID des Markdown-Dokuments mit dem Attribut id gesetzt werden. Der Standardwert der ID entspricht dem Dateinamen ohne Dateiendung (Beispiel: Die standardmäßige ID des Dokuments Einleitung.md lautet Einleitung ). Mit dem Attribut title kann der Titel des Dokuments überschrieben werden. Standardwert für den Titel eines Dokuments ist die Bezeichnung der ersten Kapitelüberschrift.

Weitere Informationen hierzu finden sich in der Docusaurus-Dokumentation (en):

• Erstellung von Dokumenten (öffnet in neuem Tab)
• Header (Front Matter) (öffnet in neuem Tab)
• Beschreibung der möglichen Attribute im Header (Front Matter) (öffnet in neuem Tab)

Markdown-Syntax

Markdown ist eine einfache Auszeichnungssprache für Texte, die ohne technische Vorkenntnisse genutzt werden kann. Die Grundelemente sind standardisiert, sodass Markdown-Dateien in gängigen Editoren gut bearbeitet werden können.

Einfache Syntax

Die wichtigsten Formatierungen sind schnell gelernt und decken die meisten Fälle ab:

• Überschriften: # bis #### am Zeilenanfang (mehr # für Unterebenen)
• Fett: **wichtiger Text**
• Kursiv: *betonter Text*
• Listen: - (Aufzählung) oder 1. (Nummerierung)

Beispiel:

# Hauptüberschrift
## Unterüberschrift
- Aufzählungspunkt 1
- Aufzählungspunkt 2

Docusaurus unterstützt neben den Standard-Elementen auch verschiedene Erweiterungen (z. B. Admonitions, Tabs oder MDX-Komponenten).

Praxistipps

• Silbentrennung: Markdown trennt Wörter nicht automatisch. Wenn Silbentrennung nötig ist, können Sie Soft Hyphens über ­ setzen.

  Beispiel:

  • Doku­mentation

• Aufklappbare Bereiche: Nutzen Sie aufklappbare Bereiche sparsam, wenn Zusatzinfos den Lesefluss stören würden. Für einfache Fälle reicht das HTML-Element <details> (mit <summary>). Wenn die Darstellung konsistent zum Docusaurus-Theme sein soll oder Sie per className stylen möchten, nutzen Sie @theme/Details.

  Beispiel:

  • Einfach: <details><summary>…</summary>…</details>
  • Theme-konsistent: import Details from '@theme/Details' und <Details summary="…">…</Details> (siehe Design: Aufklappbare Bereiche)

• Spitze Klammern im Text: Verwenden Sie < und > im Fließtext nicht direkt. Nutzen Sie stattdessen < und > (außer Sie fügen bewusst HTML oder eine React-Komponente ein).

  Beispiel:

  • a < b

• Überschriften sauber schreiben: Die # stehen am Zeilenanfang und danach folgt genau ein Leerzeichen.

  Beispiel:

  • ## Abschnittstitel

• Zum Üben: Zum risikofreien Ausprobieren der Markdown-Syntax können Sie Live-Vorschauen im Browser nutzen, z. B. markdownlivepreview.com (öffnet in neuem Tab).

  Beispiel:

  • Text links eingeben und das Ergebnis rechts prüfen
  • Danach den fertigen Markdown-Text in Ihr Docusaurus-Dokument übernehmen

• Leerzeichen am Zeilenende: Vermeiden Sie Leerzeichen am Zeilenende. Ausnahme: Für einen gewünschten Zeilenumbruch sind mindestens zwei Leerzeichen am Zeilenende nötig.

  Beispiel:

  • Zeile 1␠␠ (zwei Leerzeichen am Zeilenende)
  • Zeile 2

• Dateiende: Am Ende einer Datei steht genau eine Leerzeile.

  Beispiel:

  • Nach dem letzten Absatz folgt eine leere Zeile

• Tabellen: Jede Tabellenzeile endet mit |. Spalten können in der Trennzeile über Doppelpunkte ausgerichtet werden (links :---, rechts ---:, zentriert :---:).

  Beispiel:

  • Siehe Ausrichtung von Tabellen (öffnet in neuem Tab)

  | Linksbündig | Rechtsbündig | Zentriert |
  | :--- | ---: | :---: |
  | A | B | C |

• Tabellen bequem erstellen: Für größere Tabellen ist es oft einfacher, einen Generator zu nutzen, z. B. TableConvert (öffnet in neuem Tab) (Export als Markdown).

  Beispiel:

  • Quelldaten (z. B. aus Excel, CSV oder HTML) einfügen
  • Ausgabeformat Markdown wählen und den Code übernehmen
  • Danach im Dokument nur noch Feinschliff machen (Ausrichtung, Text)

Weiterführende Guides

• Grundlagen zur Markdown-Syntax (öffnet in neuem Tab)
• Weitere Docusaurus-spezifische Markdown-Features (öffnet in neuem Tab)

Verfügbare Komponenten und ihre Verwendung

@theme/Details

Nutzen Sie @theme/Details für aufklappbare Bereiche, wenn diese konsistent zum Docusaurus-Theme aussehen sollen oder wenn Sie Styling über className steuern möchten. Eine Alternative ist das HTML-Element <details> (siehe Design: Aufklappbare Bereiche).

Import:

import Details from '@theme/Details'

Beispiel:

<Details className="it-plr_details" summary="Titel">
  Inhalt
</Details>

@site/src/components/JobLogExplainer

Nutzen Sie diese Komponente, um den Job-Log-Explainer direkt in eine MDX-fähige Dokumentationsseite einzubetten. Die Komponente bietet die zwei Eingabemodi „URL des Verarbeitungsprotokolls (Job Log)“ und „Log-Auszug (Text)“ und spricht die API-Endpunkte unter /api/job-log-explainer an.

Import:

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

Beispiel:

<JobLogExplainer />

Dokument-Referenzierungen

Dokumente können auch untereinander verlinkt werden, wie folgendes Beispiel zeigt:

Weitere Infos:

• Markdown links (öffnet in neuem Tab)

Referenzierung von Abschnitten innerhalb eines Dokuments (interne Links)

Docusaurus generiert für alle mit einem oder mehreren Hashtag erstellten Überschriften implizit sog. Heading IDs. Beispielsweise wird für die Überschrift ### Hello World die ID hello-world erzeugt.

Entsprechend lässt sich dieser Abschnitt folgendermaßen verlinken:

[Bei "Hello world" weiterlesen](#hello-world)

Das ist jedoch aus mehreren Gründen problematisch:

• Umlaute und andere Sonderzeichen in der Überschrift werden URL-codiert. Aus dem Text "Türöffner" würde Docusaurus im Rahmen des Builds T%C3%BCr%C3%B6ffner machen.
• Wird die Überschrift geändert, ändert sich auch die von Docusaurus generierte Heading ID.

Abhilfe

Möchte man auf eine Überschift verlinken, ist es in jedem Fall ratsam, eine explizite Heading ID zu vergeben!

Bei unserem Eingangsbeispiel funktioniert das so:

### Hello World \{#my-heading}

Damit haben wir explizit my-heading als Heading ID festgelegt. Diese bleibt gleich, auch wenn wir den Text der Überschrift davor ändern.

Die Docusaurus-Dokumentation enthält weitere Informationen zu impliziten und expliziten Heading IDs (öffnet in neuem Tab).

Kommentare

Mitunter ist es erforderlich, Kommentare in einer Markdown-Datei zu hinterlegen, die auf der resultierenden Website nicht sichtbar sein sollen.

Da Docusaurus HTML-Code in Markdown-Dateien unterstützt, kann in solchen Fällen ein HTML-Kommentar in der Form

<!-- Dies ist ein Kommentar -->

verwendet werden.