diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt
index 2216b6efef..ed8e234c29 100644
--- a/docs/ref/templates/builtins.txt
+++ b/docs/ref/templates/builtins.txt
@@ -1510,6 +1510,14 @@ For example::
 
 If ``value`` is ``Tom & Jerry``, the output will be ``Tom & Jerry``.
 
+However, ampersands used in named entities and numeric character references
+will not be replaced. For example, if ``value`` is ``Café``, the output
+will *not* be ``Caf&eacute&`` but remain ``Café``. This means that
+in some edge cases, such as acronyms followed by semicolons, this filter will
+not replace ampersands that need replacing. For example, if ``value`` is
+``Contact the R&D;``, the output will remain unchanged because ``&D;``
+resembles a named entity.
+
 .. templatefilter:: floatformat
 
 floatformat