1 files changed, 15 insertions, 0 deletions

diff --git a/documentation/standards.md b/documentation/standards.md
index bc403e393e..f3d88d446b 100644
--- a/documentation/standards.md
+++ b/documentation/standards.md
@@ -109,6 +109,21 @@ or in the BitBake User Manual
 If it is not described yet, the variable should be added to the
 glossary before or in the same patch it is used, so that `:term:` can be used.
 
+### Admonitions
+
+Sphinx has predefined admonitions that can be used to highlight a bit of text or
+add a side-note to the documentation. For example:
+
+```rst
+.. note::
+
+   This is a note admonition.
+```
+
+We try to limit our usage of these admonitions to `note` and `warning`, as the
+Sphinx documentation [warns](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives)
+that most themes only style these two admonitions.
+
 ## ReStructured Text Syntax standards
 
 This section has not been filled yet