Zum Hauptinhalt springen

Admonitions (Infoboxen) verwenden

Admonitions sind hervorgehobene Infoboxen, die Inhalte gliedern und Leser:innen beim schnellen Erfassen unterstützen. Sie sollten innerhalb einer Dokumentation konsistent eingesetzt werden, damit sich Bedeutung und Dringlichkeit zuverlässig „lesen“ lassen.

Zusammenfassung

Auf dieser Seite erfahren Sie, wie Sie Admonitions in Dokumentationsseiten konsistent und verständlich einsetzen und welche Boxen sich für Infos, Praxistipps und Warnungen eignen. Als Referenz dient die offizielle Docusaurus-Dokumentation: Admonitions (öffnet in neuem Tab)

Grundprinzipien​

  • Konsistent bleiben

    Nutzen Sie Admonitions dokumentationsweit in vergleichbaren Situationen.

    Beispiel:

    • :::info für allgemeine Zusatzinfos und Verweise
    • :::tip für praxiserprobte Hinweise
    • :::warning oder :::danger für Risiken, Fehlerquellen oder Pflichtprüfungen

  • Individuelle Überschriften sparsam und wiedererkennbar verwenden

    Docusaurus lässt auch die Verwendung individueller Überschriften zu. Diese sollten möglichst gleichbleibend sein, dürfen aber bei Bedarf präzisiert werden.

    Beispiel:

    • :::info[Allgemeine Infos]
    • :::info[Weiterführende Informationen]
    • :::note[Redaktioneller Hinweis]
    • :::tip[Praxis-Tipp]

  • Komplexität in Boxen vermeiden

    Admonitions sind für kurze, fokussierte Inhalte gedacht. Verzichten Sie innerhalb von Boxen möglichst auf sehr komplexe Strukturen (z. B. viele verschachtelte Tabs).

Welche Box wofür​

  • :::info – Einordnung, Zusammenfassung, Verweise auf weitere Abschnitte oder externe Quellen
  • :::note – redaktionelle oder technische Hintergründe (z. B. „Seite im Aufbau“, „Inhalte werden migriert“)
  • :::tip – praxistaugliche Abkürzungen, Links zu Arbeitsmaterialien, hilfreiche Beispiele
  • :::warning – wichtige Hinweise, die leicht zu Fehlern führen können (z. B. Reihenfolge, Abhängigkeiten, Stolperfallen)
  • :::danger – Warnungen vor gravierenden Folgen (z. B. Datenverlust, Sicherheitsrisiken, rechtliche Pflichtverletzungen)

Syntax (Markdown)​

:::info[Allgemeine Infos]
Kurze Zusammenfassung oder Einordnung, ohne inhaltlich zu vertiefen.
:::

Ausgabe:

Allgemeine Infos

Kurze Zusammenfassung oder Einordnung, ohne inhaltlich zu vertiefen.

:::tip[Praxis-Tipp]
Links zu Arbeitsmaterialien oder ein kurzer „So klappt’s in der Praxis“-Hinweis.
:::

Ausgabe:

Praxis-Tipp

Links zu Arbeitsmaterialien oder ein kurzer „So klappt’s in der Praxis“-Hinweis.

:::warning[Achtung]
Hier steht ein wichtiger Hinweis zu einer typischen Fehlerquelle.
:::

Ausgabe:

Achtung

Hier steht ein wichtiger Hinweis zu einer typischen Fehlerquelle.

:::danger[Warnung]
Hier steht eine Warnung vor erheblichen Folgen.
:::

Ausgabe:

Warnung

Hier steht eine Warnung vor erheblichen Folgen.

Weiterführende Informationen

Mehr Informationen zu Admonitions finden Sie auf der entsprechenden Seite der Docusaurus-Dokumentation (öffnet in neuem Tab).

Hinweise für Dokumentationswebsites der öffentlichen Verwaltung​

  • Normen und Zuständigkeiten klar trennen: Rechtliche Grundlagen, Zuständigkeiten und Verfahrenshinweise gehören oft in :::info (Einordnung) oder :::warning (Pflichtprüfung), nicht in Fließtext „zwischen den Zeilen“
  • Barrierefreiheit beachten: Verlassen Sie sich nicht ausschließlich auf Farbe oder Icon, sondern benennen Sie die Aussage im Text (z. B. „Wichtig: …“, „Achtung: …“)
  • „Zusammenfassung am Anfang“ gezielt einsetzen: Eine :::info-Box am Anfang eignet sich gut für Ziel, Geltungsbereich und wichtigste Links einer Seite