How are special notes like warnings and tips represented in DITA?

In DITA, special notes like warnings and tips are typically represented using custom note types. These custom note types allow for the structured and consistent presentation of information that goes beyond generic notes.

Special notes, such as warnings and tips, often require specific formatting and content elements. Rather than using a generic <note> element for all types of notes, DITA allows the creation of custom note types tailored to documentation needs.

Creating and Representing Custom Note Types

Define Custom Note Types:

Create custom note types for different types of special notes, like warnings or tips. These custom note types are typically based on the <note> element but extended to include additional elements and attributes.

Specify Attributes and Content:

Define attributes and content structures specific to each custom note type. This may include attributes like severity for warnings or icon for tips, as well as specific child elements like cause and action for warnings.

Apply Custom Note Types:

In DITA topics, apply the relevant custom note type to convey the intended information. Use the defined attributes and elements to provide the necessary details.

Formatting and Styling:

Create formatting rules or stylesheets to ensure that these custom note types are presented consistently across the documentation set. This includes defining how the warning and tip notes should appear in the output, considering elements like icons, text formatting, and borders.


This sample creates custom note types for warnings and tips.

<!-- Custom warning note type -->
<!ELEMENT warning (cause, action)>
<!ATTLIST warning
          severity (low | medium | high) "medium"
          reason CDATA #IMPLIED>

<!-- Custom tip note type -->
<!ELEMENT tip (content)>
          icon (lightbulb | info) #REQUIRED>

In this example, two custom note types, <warning> and <tip>, are defined. The <warning> note type includes attributes for severity, reason, and specific child elements (cause and action). The <tip> note type includes an icon attribute and a content element. These custom note types can be used to represent warnings and tips in DITA topics.