ISO-konforme Hinweisblöcke in AsciiDoc schreiben

ISO 7010 und ISO 3864 verstehen

Zwei zentrale Normen regeln Sicherheitskennzeichen:

• ISO 7010 legt standardisierte Sicherheitszeichen fest und sorgt für weltweite Wiedererkennung.

• ISO 3864 definiert die Farben und geometrischen Formen für Sicherheitsbotschaften.

Diese Normen konzentrieren sich auf bestimmte Farben:

Die Anatomie von Hinweisen in CSS

Hinweis-Blöcke (auch Admonitions genannt) verwenden Namenskonventionen in ihren CSS-Klassen, um die Art der Sicherheitsbotschaft zu kodieren. Die CSS-Selektoren greifen anschließend auf bestimmte Strukturelemente innerhalb dieser Blöcke zu.

1. Grundstruktur

Jeder Admonition-Block beginnt mit der Klasse .admonitionblock und einer kategoriespezifischen Klasse wie caution.

<div class="admonitionblock caution">…</div>

AsciiDoc liefert fünf Admonition-Typen mit:

• TIP:

• NOTE:

• CAUTION:

• WARNING:

• IMPORTANT:

Wie Sie weiter unten sehen werden, lässt sich das jedoch beliebig erweitern.

2. Admonitionen sind Tabellen mit zwei Zellen

Innerhalb jedes Admonition-Blocks befindet sich in der Regel eine Tabelle mit zwei Zellen:

<table>
  <tr>
    <td class="icon">…</td>
    <td class="content">…</td>
  </tr>
</table>

Selektoren wie:

.admonitionblock td.icon {}
.admonitionblock td.content {}

adressieren die jeweilige Zelle abhängig vom Block-Typ.

Schritt-für-Schritt-Einrichtung

Nachfolgend zeigen wir Ihnen mehrere Möglichkeiten, ISO-Admonitionen hinzuzufügen. Die erste erfordert etwas CSS-Aufwand, die übrigen konzentrieren sich auf reine AsciiDoc-Funktionen.

adoc Studio für Mac, iPad & iPhone

Technische Dokumentation
in AsciiDoc erstellen

14 Tage gratis testen →

Option 1) Eigenes Stylesheet

Ziel: Schreiben Sie im AsciiDoc-Quelltext nur den ISO-Code. Das Stylesheet übernimmt automatisch die passende Gestaltung.

[TIP.e001]
====
Halten Sie Fluchtwege stets frei.
====

Bevor Sie starten, wählen Sie Ihren Ansatz:

• Von Grund auf: Verwenden Sie dieses ISO-Stylesheet als primäre Basis.

• Modular: Legen Sie das ISO-Stylesheet über Ihr bestehendes Design. Empfohlen für Einfachheit und Flexibilität.

Für den modularen Ansatz:

• Wählen Sie ISO.adocstyle in adoc Studio.

• Passen Sie info.json im ISO-Stylesheet-Paket an und setzen Sie Ihren bevorzugten Basisstil:

"basedOn": "app.adoc-studio.style.manual"

Jetzt können Sie mit der CSS-Datei beginnen.

1. ISO-Farben als CSS-Variablen definieren

Definieren Sie ISO-Standardfarben eindeutig:

:root {
  --iso-safety-yellow: #F9A900; /* Warnung */
  --iso-safety-red: #9B2423; /* Verbot/Feuer */
  --iso-safety-blue: #005387; /* Gebot/Information */
  --iso-safety-green: #237F52; /* Rettung */
  --iso-safety-white: #ECECE7; /* Hintergrund & Symbol */
  --iso-safety-black: #2B2B2C; /* Symbol */
}

2. Bestehende Styles überschreiben (optional)

Notwendig, wenn Sie das Stylesheet über ein bestehendes legen:

.admonitionblock[class*="e0"],
.admonitionblock[class*="f0"],
.admonitionblock[class*="m0"],
.admonitionblock[class*="p0"],
.admonitionblock[class*="w0"] {
  /* Hier überschreiben Sie bestehende Admonition-Stile */
}

3. Eigene Klassen definieren und gestalten

Weisen Sie Farben und SVG-Icons per Klasse zu:

/* Standard-Icon durch ISO-Piktogramm ersetzen */

.admonitionblock[class*="e0"] td.icon::before,
.admonitionblock[class*="f0"] td.icon::before,
.admonitionblock[class*="m0"] td.icon::before,
.admonitionblock[class*="p0"] td.icon::before,
.admonitionblock[class*="w0"] td.icon::before {
  content: "";
  background: var(--adm-current-icon) no-repeat center/contain;
}

/* Klassenabhängige Farbgebung */

.admonitionblock[class*="e0"] td.content {
  border-left: var(--ads-adm-iso-border-width) solid var(--iso-safety-green);
  background: var(--iso-safety-green-bg) !important;
}

/* Fallbacks (optional) */

.admonitionblock[class*="e0"] {
  --adm-current-icon: url("images/E001.svg");
}

Wiederholen Sie dies analog für alle ISO-Klassen (f0, m0, p0, w0).

4. Piktogramme zuordnen

Nun listen Sie alle spezifischen Piktogramm-Klassen auf und verknüpfen Codes mit SVG-URLs:

.admonitionblock.e001 { --adm-current-icon: url("images/E001.svg"); }

5. PDF- und Dark-Mode-Anpassungen

Sorgen Sie für konsistente Darstellung in allen Ausgaben:

/* PDF-Anpassungen */
@media vivliostyle {
  /* PDF-spezifisches Styling */
}

/* Dunkelmodus-Anpassungen */
@media (prefers-color-scheme: dark) {
  /* Dark-Mode-Styling */
}

Sie verfügen nun über ein effizientes, wiederverwendbares Stylesheet für ISO-konforme Admonitionen.

Laden Sie das ISO-Stylesheet auf unserer Website herunter. Ziehen Sie es in das Produkt-Styles-Menü oder in das Vorschaufenster. Bei Fragen kontaktieren Sie uns gern direkt via E-Mail.

Option 2) Includes und Bedingungen nutzen

Ziel: Halten Sie Ihre Haupt-AsciiDoc-Datei schlank, indem Sie Piktogramm, Titel und Erklärung in einen wiederverwendbaren Include auslagern. Setzen Sie dafür vor jedem Include-Aufruf die drei Dokumentattribute (sign, sign-title, sign-text). Fehlt ein Wert, fügt ein kurzes ifndef-Block einen sinnvollen Standard ein.

1. ISO-Schilder in einer neuen Datei definieren

Das folgende Fragment (include.adoc) prüft, ob die drei Attribute definiert sind. Andernfalls werden ein Standard-Piktogramm E003, ein Standardtitel und eine Standardbeschreibung gesetzt. Anschließend erzeugt es eine Tabelle mit zwei Spalten: links das SVG, rechts fettgedruckter Titel und Beschreibung.

ifndef::sign[]
:sign: E003
endif::[]

ifndef::sign-title[]
:sign-title: Notausgang (linke Seite)
endif::[]

ifndef::sign-text[]
:sign-text: Dieses Schild weist den Weg zu einem Notausgang auf der linken Seite.
endif::[]

[cols="2,9", frame=none, grid=none, role=iso-emergency]
|===
| image:https://www.adoc-studio.app/includes/safety-signs/emergency/{sign}[width=100]
| *{sign-title}* +
{sign-text}
|===

:!sign:
:!sign-title:
:!sign-text:

2. Include in Ihrem Dokument platzieren

Setzen oder überschreiben Sie in der Hauptdatei die drei Attribute, rufen Sie include::include.adoc[] auf, löschen Sie die Attribute und fahren Sie fort. Das Beispiel zeigt zwei unterschiedliche Schilder im selben Abschnitt – ohne Duplikate.

// Schild #1 – nutzt eigenes Piktogramm, übernimmt sonst Standards
:sign: E001
:sign-title: Ausgang links
:sign-text: Ausgang links
include::include.adoc[]

// Schild #2 – komplett andere Inhalte, gleicher Include-Aufruf
:sign: E003
:sign-title: Eigener Titel
:sign-text: Zusätzlicher Text.
include::include.adoc[]