--- a/doc/components.rst	Sun Jul 10 16:15:09 2022 +0200
+++ b/doc/components.rst	Sun Jul 10 16:15:44 2022 +0200
@@ -237,6 +237,13 @@
   An integer value indicating the maximum number of comment nodes that can be created. See
   :ref:`ap-xmpp-threads-conversion`
 
+``auto_mentions``
+  A boolean value indicating if received XMPP pubsub blog items bodies must be scanned to
+  find ``@user@server.tld`` type mentions. If mentions are found, they'll be added to the
+  resulting AP items.
+
+  **default**: ``true``
+
 
 .. _ap-actor-from-xmpp:
 
@@ -589,7 +596,7 @@
 
 The gateway does the conversion between XMPP identity and AP actor metadata.
 
-XMPP "identity" is actually a compilaton of data coming from various locations and in
+XMPP "identity" is actually a compilation of data coming from various locations and in
 particular `XEP-0292 (vCard4 Over XMPP)`_. In those data, vCard's ``nickname`` (first
 found) is used as AP ``name`` field, and vCard's ``note`` is used as AP's ``summary``
 (it's generally a self-description of users).
@@ -605,6 +612,56 @@
 .. _XEP-0084 (User Avatar): https://xmpp.org/extensions/xep-0084.html
 .. _XEP-0054 (vcard-temp): https://xmpp.org/extensions/xep-0054.html
 
+Mentions
+~~~~~~~~
+
+Mentions are converted by the gateway under some conditions explained below.
+
+When receiving an AP item which converts to a pubsub item (i.e. not a direct message), for
+any local user mentioned (using a tag of type ``Mention``) or directly specified in a
+target field (``to``, ``bto``, ``cc`` or ``bcc``), a `XEP-0372 (References)`_ type mention
+will be emitted.
+
+This is not done for direct message as the recipients are already specified, and sending
+reference is most probably not desired for a private message.
+
+In the direction XMPP 🠞 ActivityPub, it's more complicated because XMPP sends references
+separately from the pubsub item, while ActivityPub links them in the same item.
+
+If a XEP-0372 reference targeting an AP actor is received and anchor a pubsub item, the
+item will be looked after in cache. If found, it will be converted to an AP item, a
+mention will be added, and the item will be delivered to the mentioned entity.
+
+This only works if the mentioned actor is on a server which has not already received the
+original item, because otherwise the AP implementation will most probably ignore the new
+item which has the same ID.
+
+It is hard to avoid sending first published item, then the same item with the reference,
+because XEP-0372 references are received after the published items.
+
+To work around that, when an XMPP blog item is received, its body is scanned to find
+``@user@server.tld`` type mention, and if found a mention is automatically added to the
+resulting AP item.
+
+It is not ideal to parse the body, but that's an acceptable trade-off to make mention
+working. This behaviour is activated by default, but can be deactivated by setting
+``auto_mentions`` option to ``false``. Auto mentions are only used for pubsub items, and
+not for direct messages for the same reason as mention are not checked in AP direct
+messages (see above).
+
+.. note::
+
+   For auto mentions, it's the AP actor handle which must be used, not the corresponding
+   virtual JID.
+
+   If you want to mention ``louise@example.org`` then you must use directly
+   ``@louise@example.org``, and NOT something like
+   ``@louise\40example.org@ap.example.net``.
+
+   To mention XMPP entities, your client must use XEP-0372 references directly.
+
+.. _XEP-0372 (References): https://xmpp.org/extensions/xep-0372.html
+
 Using the Component (for developers)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~