Admonitions

[Quick Quiz]

Admonitions are visually distinct elements used in documentation to highlight information relevant to the context. They draw attention through icons, borders, or background colors, and are especially useful for conveying critical guidance such as warnings, tips, or notes that readers should not overlook.

This chapter describes the types of admonitions used in Espressif documentation and provides guidelines for their selection, formatting, and usage.

Types of Admonitions

Espressif documentation supports the following admonition types:

Tip:

Offers helpful advice or best practices that can improve user efficiency. Use when the information is optional but enhances the experience—for example, shortcuts, recommendations, or more efficient alternatives.

Example:

Tip

Configure the board settings in the preferences file to save time.
Note:

Adds supplementary information that expands on the main content. Use when the information clarifies a point but is not essential to proceed.

Example:

Note

The Espressif download server currently does not mirror everything from GitHub, but only files attached as Assets to some releases, as well as source archives for some releases.
Important:

Highlights crucial information that must be understood or followed for successful completion of a task. Use to communicate prerequisites or essential steps.

Example:

Important

idf.py should be run in an ESP-IDF project directory, i.e., a directory containing a CMakeLists.txt file. Older style projects that contain a Makefile will not work with idf.py.
Caution:

Advises careful attention due to possible undesirable outcomes. Use when ignoring the advice may result in errors or unexpected behavior.

Example:

Caution

Writing incorrect calibration data is irreversible and cannot be modified afterward.
Warning:

Signals a serious risk or danger, such as hardware damage or data loss. Use when non-compliance may lead to severe consequences.

Example:

Warning

It is strictly prohibited to connect a 3.6 V rechargeable battery, as the voltage of a fully charged 3.6 V battery can reach around 4 V. Since the input voltage range for the VBAT pin is 2.3 V – 3.6 V, this could potentially damage the VBAT pin.

Choose the Right Admonition

Use the table below to select the appropriate admonition based on content type, importance, consequence, and urgency.

Content Type	Essential?	Consequence if Ignored	Urgency	Admonition
Helpful advice or shortcuts	No	None	No	Tip
Additional context or clarifications	No	None	No	Note
Required steps or conditions	Yes	Moderate	No	Important
Possible errors or misbehavior	Yes	Moderate	Yes	Caution
Serious risk of damage or data loss	Yes	Severe	Yes	Warning

Severity Hierarchy:

The levels of admonition severity increase as follows:

Tip < Note < Important < Caution < Warning
Consider Your Audience:

Adapt the admonition based on the reader’s experience level. What might be a Tip for advanced users could be an Important point for beginners.

For example, a keyboard shortcut might be optional for experts (a Tip) but crucial for novices to complete a task efficiently (an Important).

Formatting Admonitions

In reStructuredText Documents

Sphinx provides built-in directive styles. Use the following syntax:

.. tip::

   This is a formatted tip in .rst.

.. note::

   This is a formatted note in .rst.

.. important::

   This is a formatted important message in .rst.

.. caution::

   This is a formatted caution in .rst.

.. warning::

   This is a formatted warning in .rst.

Rendering examples:

Tip

This is a formatted tip in .rst.

Note

This is a formatted note in .rst.

Important

This is a formatted important message in .rst.

Caution

This is a formatted caution in .rst.

Warning

This is a formatted warning in .rst.

In LaTeX Documents

In LaTeX, admonitions can be formatted using various packages and custom environments to ensure consistency and visual appeal.

Load Required Packages

Use the mdframed and xcolor packages to create styled boxes for admonitions.
```
\usepackage{mdframed}
\usepackage{xcolor}
```

Define Custom Colors

In LaTeX documents of Espressif, it is recommended to use the following colors for admonitions.

\definecolor{ForestGreen}{HTML}{2C6B2F}
\definecolor{GoldenDreamColor}{HTML}{1020A0}
\definecolor{DarkOrange}{HTML}{D46B2D}
\definecolor{AllportsColor}{HTML}{A02010}

Define Title Translations

For multilingual support, define the translations for admonition titles. Below are the suggested translations used in LaTeX documents of Espressif.

% Tip
\DeclareTranslation{English}{framedtxttip}{Tip:}
\DeclareTranslation{chinese}{framedtxttip}{提示：}


% Note
\DeclareTranslation{English}{framedtxtnote}{Note:}
\DeclareTranslation{chinese}{framedtxtnote}{说明：}

%Important
\DeclareTranslation{English}{framedtxtimportant}{Important:}
\DeclareTranslation{chinese}{framedtxtimportant}{重要：}

% Caution
\DeclareTranslation{English}{framedtxtcaution}{Caution:}
\DeclareTranslation{chinese}{framedtxtcaution}{小心：}

% Warning
\DeclareTranslation{English}{framedtxtwarning}{Warning:}
\DeclareTranslation{chinese}{framedtxtwarning}{警告：}

Define Admonition Environments

Add the following definitions to the preamble:

% Tip
\newenvironment{tiplisting}
{\small\mdframed[middlelinewidth=0.5pt, middlelinecolor=ForestGreen, skipabove=15pt]{ \textbf{{\color{ForestGreen} \GetTranslation{framedtxttip}}}}}
{\endmdframed\vspace{12pt}\normalsize}

% Note
\newenvironment{notelisting}
{\small\mdframed[middlelinewidth=0.5pt, middlelinecolor=GoldenDreamColor, skipabove=15pt]{\textbf{{\color{GoldenDreamColor} \GetTranslation{framedtxtnote}}}}}
{\endmdframed\vspace{12pt}\normalsize}

% Important
\newenvironment{importantlisting}
{\small\mdframed[middlelinewidth=0.5pt, middlelinecolor=DarkOrange, skipabove=15pt]{\textbf{{\color{DarkOrange} \GetTranslation{framedtxtimportant}}}}}
{\endmdframed\vspace{12pt}\normalsize}

% Caution
\newenvironment{cautionlisting}
{\small\mdframed[middlelinewidth=0.5pt, middlelinecolor=AllportsColor, skipabove=15pt]{\textbf{{\color{AllportsColor} \GetTranslation{framedtxtcaution}}}}}
{\endmdframed\vspace{12pt}\normalsize}

% Warning
\newenvironment{warninglisting}
{\small\mdframed[middlelinewidth=0.5pt, middlelinecolor=AllportsColor, skipabove=15pt]{\textbf{{\color{AllportsColor} \GetTranslation{framedtxtwarning}}}}}
{\endmdframed\vspace{12pt}\normalsize}

Use in Document Body

After defining the environments, use them in the document as follows:

\begin{tiplisting}
  \item Configure the board settings in the preferences file to save time.
\end{tiplisting}

\begin{notelisting}
  \item Keep the port name handy as you will need it in the next steps.
\end{notelisting}

\begin{importantlisting}
  \item Enabling flash encryption limits the options for further updates of ESP32-C3. Before using this feature, read the document and make sure to understand the implications.
\end{importantlisting}

\begin{cautionlisting}
  \item Any changes or modifications not expressly approved by the party responsible for compliance could void the user’s authority to operate the equipment.
\end{cautionlisting}

\begin{warninglisting}
  \item The transport should be valid during the client lifetime and is destroyed when esp\_mqtt\_client\_destroy is called.
\end{warninglisting}

Rendering examples:

Usage Guidelines

Consistency:

Apply a consistent style for each admonition type, including icons, borders, and tone.
Relevance:

Ensure the admonition is directly related to the content and adds value to the reader.
Placement:

Place admonitions close to the related content.
Frequency:

Use sparingly. Overuse, especially of Warning or Caution, can lead to alert fatigue, where readers start to ignore them.
Localization:

Translate both titles and content while preserving the original tone and severity.

Note

Default translations may vary across formats (e.g., reStructuredText vs. LaTeX). Customize localization files (such as sphinx.po) or LaTeX preambles to ensure consistency.

Provide feedback about this document