Styles for notes and warnings in online documentation

Because notes and warnings should act as eye-catchers to some degree, they are among the few places in an online documentation where some room remains for a visually appealing design. Not every authoring tool provides appropriate on-board tools for this, but even a little additional CSS code can make a big difference.

As warnings and other notes typically occur very frequently in a technical documentation, it is particularly important to be able to insert and edit them in the authoring tool with little effort.

Below you can find a small collection of solutions that can be flexibly integrated.

Example 1: Basic variant with auto text

In the best case, the signal words such as “Warning” or “Important” are part of the format and do not need to be entered at all. However, the disadvantage is that these texts must then also be translated into possible foreign languages in the CSS code, which is not compatible with all translation workflows. (Tip: If necessary, create all texts contained in CSS files as CSS variables and collect them in a single place.)

In the following example, the text “Important: ” (including the colon and the space character) comes from a style setting in the CSS code. If you assign the defined style to a paragraph, the text appears automatically and the paragraph is formatted as follows:

Here goes some information that readers must not miss.

The fact that the style is assigned to a paragraph here has both advantages and disadvantages:

▪Advantage: The style can be assigned directly and does not require any opening or closing element.

▪Disadvantage: The note can only consist of a single paragraph (each additional paragraph would create a new note). Although manual line breaks are possible within this paragraph (Shift+Enter), appropriate spacing may be difficult and bulleted or numbered lists cannot be used.

Implementation for example 1

Step 1: Add the following CSS code to the CSS file used by your online documentation or to the head section of your page template:


.note-important {
 border-left: solid 7px #006699;
 border-top: solid 1px #f0f7fb; 
 border-right: solid 1px #f0f7fb; 
 border-bottom: solid 1px #f0f7fb; 
 border-radius: 5px 0 0 5px;
 background-color: #f0f7fb;
 line-height: 18px;
 overflow: hidden;
 padding: 12px;
}
.note-important::before {
 content: "Important: ";
 font-weight: bold;
}

Step 2: Assign the style note-important to the paragraphs that you want to become a note.

Example 2: Variant that supports multiple paragraphs

The next variant consists of multiple paragraphs and a list.

Important:

Put your important information here. Put your important information here. Put your important information here.

▪Observe this.

▪Observe that.

▪Observe the other.

Implementation for example 2

Step 1: Add the following CSS code to the CSS file used by your online documentation or to the head section of your page template:


.noteblock {
  background-color: #f0f7fb;
  border-left: solid 4px #006699;
  overflow: hidden;
  padding: 12px 20px 14px 20px;
}

Step 2: In the text, place the note between the following two HTML snippets:


<div class="noteblock">


</div>

Example 3: Character placed on the side

The following examples use a single character from any font as a symbol.

Caution: Here goes your warning message. Here goes your warning message.

Important: Here goes your important note. Here goes your important note.

Tip: Here goes your tip. Here goes your tip.

Implementation for example 3

Step 1: Add the following CSS code to the CSS file used by your online documentation or to the head section of your page template:


.side-warning {
  border: 1px solid #CB101E;;
  border-radius: 5px;
  color: var(--used-color);
  margin-bottom: 32px;
  margin-top: 16px;
  padding-left: 16px;
  padding-right: 16px;
  position: relative;  
}
.side-warning::before {
  align-items: center;
  background-color: #CB101E;;
  border-radius: 50%;
  color: #fff;
  content: "!";
  display: flex;
  font-family: monospace;
  font-size: 16px;
  font-weight: 700;
  height: 24px;
  justify-content: center;
  left: -12px;
  line-height: 1;
  position: absolute;
  top: -12px;
  width: 24px;
}
.side-note {
  border: 1px solid #727272;
  border-radius: 5px;
  color: #727272;
  margin-bottom: 32px;
  margin-top: 16px;
  padding-left: 16px;
  padding-right: 16px;
  position: relative;  
}
.side-note::before {
  align-items: center;
  background-color: #727272;
  border-radius: 50%;
  color: #fff;
  content: "!";
  display: flex;
  font-family: monospace;
  font-size: 16px;
  font-weight: 700;
  height: 24px;
  justify-content: center;
  left: -12px;
  line-height: 1;
  position: absolute;
  top: -12px;
  width: 24px;
}
.side-tip {
  border: 1px solid #006699;
  border-radius: 5px;
  color: var(--used-color);
  margin-bottom: 32px;
  margin-top: 16px;
  padding-left: 16px;
  padding-right: 16px;
  position: relative;  
}
.side-tip::before {
  align-items: center;
  background-color: #006699;
  border-radius: 50%;
  color: #fff;
  content: "✓";
  display: flex;
  font-family: monospace;
  font-size: 16px;
  font-weight: 700;
  height: 24px;
  justify-content: center;
  left: -12px;
  line-height: 1;
  position: absolute;
  top: -12px;
  width: 24px;
}

Step 2: Assign the desired style either to a single paragraph, or place the note between the following two HTML snippets:


<div class="side-warning">


</div>

(To apply the other two styles, replace side-warning with side-note or with side-tip.)

Example 4: Symbol placed on the side

Simple yet eye-catching are the following styles using a “flat design”.

Note: You could also implement these designs styles with a table if you don’t want to go beyond what your authoring tool covers or if you need the same style also for PDF output and your authoring tool doesn’t use CSS when creating PDF.

Caution

Here goes your warning message. Here goes your warning message. Here goes your warning message. Here goes your warning message. Here goes your warning message.

Important

Here goes your important note. Here goes your important note. Here goes your important note. Here goes your important note. Here goes your important note. Here goes your important note. Here goes your important note.

Tip

Here goes your tip. Here goes your tip. Here goes your tip. Here goes your tip. Here goes your tip. Here goes your tip. Here goes your tip. Here goes your tip. Here goes your tip. Here goes your tip.

Implementation for example 4

Step 1: Add the following CSS code to the CSS file used by your online documentation or to the head section of your page template:

Note that you may need to adjust the paths and the names of the images.


.the-warning {
  display: grid;
  grid-template-columns: 43px 1fr;
  align-items: center;
  padding: 14px 23px 14px 20px;
  background: #FEF1F2;
  box-shadow: inset 43px 0 0 0 #CB101E;
}
.the-warning::before {
  content: "";
  display: block;
  margin-top: 0px;
  margin-bottom: 0px;
  margin-left: -13px;
  margin-right: auto;
  width: 30px;
  height: 30px;
  background-image: url("YOUR-PATH/warning.svg");
  background-size: 30px;
  background-repeat: no-repeat;
}
.the-note {
  display: grid;
  grid-template-columns: 43px 1fr;
  align-items: center;
  padding: 14px 23px 14px 20px;
  background: rgb(249,249,249);
  box-shadow: inset 43px 0 0 0 #727272;
}
.the-note:before {
  content: "";
  display: block;
  margin-top: 0px;
  margin-bottom: 0px;
  margin-left: -13px;
  margin-right: auto;
  width: 30px;
  height: 30px;
  background-image: url("YOUR-PATH/warning.svg");
  background-size: 30px;
  background-repeat: no-repeat;
}  
.the-tip {
  display: grid;
  grid-template-columns: 43px 1fr;
  align-items: center;
  padding: 14px 23px 14px 20px;
  background: #f0f7fb;
  box-shadow: inset 43px 0 0 0 #006699;
}
.the-tip::before {
  content: "";
  display: block;
  margin-top: 0px;
  margin-bottom: 0px;
  margin-left: -13px;
  margin-right: auto;
  width: 30px;
  height: 30px;
  background-image: url("YOUR-PATH/note.svg");
  background-size: 30px;
  background-repeat: no-repeat;
}

Step 2: Assign the desired style either to a single paragraph, or place the note in the text between the following two HTML snippets:


<div class="the-warning">


</div>

(To apply the other two styles, replace the-warning with the-note or with the-tip.)

Alternative designs

These styles can also be modified, for example:

▪background on the right is light gray instead of colored

▪background on the right is white instead of colored, and outlined with a thin line

▪background both on the right and on the left is light gray or white but with a colored symbol instead

▪corners are rounded …

If you want the icon to be at the top instead of in the center, change the statement align-items: center; to align-items: top in the CSS code.

Symbol plus box

Finally, another variant is this one:

Note:

Here goes your note. Here goes your note. Here goes your note. Here goes your note. Here goes your note. Here goes your note. Here goes your note.

Implementation for example 5

Step 1: Add the following CSS code to the CSS file used by your online documentation or to the head section of your page template:

Note that you may need to adjust the paths and the names of the images.


.note-variant {
  display: grid;
  grid-template-columns: 33px 1fr;
  align-items: normal;
  padding: 0px 23px 14px 20px;
  background: white;
  box-shadow: inset 33px 0 0 0 white;
  border: 1px solid #727272;
}    
.note-variant::before {
  content: "";
  display: block;
  margin-top: 0px;
  margin-bottom: 0px;
  margin-left: -20px;
  margin-right: auto;
  width: 35px;
  height: 35px;
  background-image: url("YOUR-PATH/note-box.svg");  
  background-position: center left;
  background-size: 35px;
  background-repeat: no-repeat;
}

Step 2: Place the note in the text between the following two HTML snippets:


<div class="note-variant">
 <div>


 </div>
</div>

___

Did you benefit from this information?

In return, please link to this page, mention the page on social media, or buy one of my books.

Thank you!