How to Write ISO-Ready Admonitions in AsciiDoc

Understanding ISO 7010 and ISO 3864

Two key standards regulate safety signs:

• ISO 7010 specifies standardized safety signs, ensuring global recognition.

• ISO 3864 defines the colors and geometric forms for safety messages.

These standards focus on specific colors:

The Anatomy of Admonitions in CSS

Admonition blocks use a naming convention in their CSS classes to encode the type of safety message they represent. The CSS selectors then target specific structural elements inside those blocks.

1. Base Structure

Each admonition block starts with the class .admonitionblock and a category-specific class such as caution.

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

There are 5 built-in admonition types in AsciiDoc:

• TIP:

• NOTE:

• CAUTION:

• WARNING:

• IMPORTANT:

However, as we'll learn below, there is plenty of room for customization.

2. Admonitions are Tables with Two Cells

Within each admonition block, the structure typically includes a table with two cells:

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

Selectors like:

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

target the respective cell depending on the block type.

Step-by-Step Setup

We'll go through several ways on how to add ISO-admonitions. The first one will require a bit of CSS work, the others focus on AsciiDoc functionality.

adoc Studio for Mac, iPad & iPhone

Create Technical Documentation
with AsciiDoc

Free 14-Day Trial

Option 1) Custom Stylesheet Setup

Goal: Write only the ISO code in your AsciiDoc source. The stylesheet automatically styles the admonition accordingly:

[TIP.e001] 
==== 
Ensure exit routes remain clear. 
====

Before we start, you need to choose your approach:

• Start from Scratch: Use this ISO stylesheet as your primary base.

• Modular Setup: Apply the ISO stylesheet on top of your existing style. Recommended for simplicity and flexibility.

To use the modular approach:

• Select ISO.adocstyle in adoc Studio.

• Modify info.json within the ISO stylesheet package, setting your preferred base style:

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

Now you can start to work in your CSS file.

1. Define ISO Colors as CSS Variables

Establish ISO-standard colors clearly:

:root {
  --iso-safety-yellow: #F9A900; /* Warning */
  --iso-safety-red: #9B2423; /* Prohibition/Fire Equipment */
  --iso-safety-blue: #005387; /* Mandatory actions/Information */
  --iso-safety-green: #237F52; /* Safe conditions */
  --iso-safety-white: #ECECE7; /* Backgrounds and Symbol */
  --iso-safety-black: #2B2B2C; /* Symbol */
}

2. Override Existing Styles (Optional)

Necessary when layering over existing stylesheets:

.admonitionblock[class*="e0"],
.admonitionblock[class*="f0"],
.admonitionblock[class*="m0"],
.admonitionblock[class*="p0"],
.admonitionblock[class*="w0"] {

   /* Add Rules to Override Admonition Styling */

}

3. Define and Style Custom Classes

Apply colors and SVG icons via classes:

/* Replace Standard Icon with ISO Pictogram */

.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;
   ...
}


/* Class-Specific Coloring */

.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; 
}


/* 
Add Fallbacks (Optional)
This always shows first ISO symbol in the class when only typing "[.e0]"
*/

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

Repeat similarly for all ISO classes (f0, m0, p0, w0).

4. Map Pictograms

Now list all specific pictogram classes mapping codes to SVG URLs:

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

5. PDF and Dark Mode

Ensure consistency across outputs:

/* PDF Adjustments */

@media vivliostyle {
  /* PDF-specific styling */
}

/* Dark Mode Adjustments */

@media (prefers-color-scheme: dark) {
  /* Dark mode styling */
}

Now you have an efficient, reusable stylesheet for ISO-compliant admonitions.

Download the ISO stylesheet from our website. Drag and drop into your product styles menu or preview pane. For feedback or questions, contact us directly.

Option 2) Use Includes and Conditions

Goal: Keep your main AsciiDoc file tidy by moving the pictogram, title and explanatory text into a single reusable include. You then set three document attributes (sign, sign-title, sign-text) before each include call. If a value is missing, a sensible default is injected by a short ifndef block.

1. Define the ISO Signs in a new Document.

The fragment below (include.adoc) checks whether the three attributes are already defined. If not, it assigns a default pictogram E003, a default title and a default description. It then lays out a two-column table whose first cell shows the SVG and whose second cell shows the bold title plus explanatory text.

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

ifndef::sign-title[]
:sign-title: Emergency exit (left hand)
endif::[]

ifndef::sign-text[]
:sign-text: This sign indicates the direction to an emergency exit on the left side.
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. Place the Include in your Document

In your main document you simply set or override the three attributes, call include::include.adoc[], clear the attributes, and move on. The second example demonstrates two different signs in the same chapter without duplication.

// Sign #1 – uses custom pictogram and inherits defaults for everything else
:sign: E001
:sign-title: Exit on the left side
:sign-text: Exit on the left side
include::include.adoc[]

// Sign #2 – completely different content, same include call
:sign: E003
:sign-title: Here come my own title
:sign-text: And some additional text.
include::include.adoc[]