Notes and information boxes

Use information boxes or paragraphs to bring attention to a piece of information.

Use your own judgment to decide which type of information box is most appropriate for the context. The following table provides a guide to the most common purposes.

Admonition	Severity	Description	Example admonition
Warning	High	Use Warning if the information or task could result in irretrievable data loss. Also include a suggestion to back up the data they might lose.	Warning: The following task overwrites several files in your Project folder. These cannot be restored after Unity overwrites them. Before you start this task, back up any files you do not want to lose.
Important	Medium	Use Important if the information or task does not carry a danger of data loss, but does have some other consequence that is not immediately obvious, such as future code rewrites. If possible, include guidance on how to prevent this consequence.	Important: When you change the properties of a prefab, Unity automatically updates the other instances of that prefab in the Scene. If you do not want this to happen, [...].
Note	Medium	Use Note to provide peripheral information that the user should be aware of, but which does not put any part of their project at risk. Only place information in a Note if it contains something that you want to highlight or emphasize. In other cases, consider whether you can integrate the information into the main text.	Note: Unity supports Android 4.4 and later versions.
Tip	Low	Use Tip to offer advice that helps the reader optimize their work or workflow. It might be a reminder of a technique, or a clue on how to complete an exercise.	Tip: To edit all Rigidbody components at once, select all GameObjects that contain one, and then use the Rigidbody Inspector to apply the same change to each GameObject in the selection.

note

Don't group a series of random tips into a Tips and Tricks section. Instead, add the tips in context, where they are most helpful to the user. If you’re not sure where or how to fit a piece of information in, discuss it in the #unity-style-guide Slack channel.

Style

Keep information boxes a brief as possible. If relevant, include a suggestion or solution. In most cases, an information box contains no more than three sentences.

Always offer warnings and cautions before the information or task they relate to. If you’re not sure where or how to fit it in, discuss it in the #unity-style-guide Slack channel.

Formatting

Where possible, use the information box formatting available in your content platform. For information about using the admonitions component in Hexadocs, refer to Notes, tips, and admonitions.

If your platform doesn't have information boxes, then add the callout to the page manually. Use a separate paragraph in the main body of the page. Write the leader (for example, "Note," "Tip," or "Warning") in bold, followed by a colon in regular font. Write the message in the same paragraph as the leader, in regular text with appropriate formatting for the content.

Example callout for a platform without information boxes
Warning: The following task overwrites several files in your Project folder. These cannot be restored after Unity overwrites them. Create a backup before you start this process.