diff --git a/content/client-server-api/modules/mentions.md b/content/client-server-api/modules/mentions.md
index 21ac54c0..22f30076 100644
--- a/content/client-server-api/modules/mentions.md
+++ b/content/client-server-api/modules/mentions.md
@@ -43,6 +43,17 @@ the localpart of Matrix IDs and display names it is recommended that clients inc
 a `m.mentions` property on each event. If there are no mentions to include it can
 be an empty object.
 
+{% boxes/rationale %}
+In previous versions of the specification, mentioning users was done by
+including the user's display name or the localpart of their Matrix ID and room
+mentions were done by including the string "@room" in the plaintext `body` of
+the event. This was prone to confusing and buggy behaviour.
+
+See the [`.m.rule.contains_display_name`](#_m_rule_contains_display_name),
+[`.m.rule.contains_user_name`](#_m_rule_contains_user_name), and
+[`.m.rule.roomnotif`](#_m_rule_roomnotif) deprecated push rules.
+{% /boxes/rationale %}
+
 #### Client behaviour
 
 In addition to using the appropriate `Matrix URI` for the mention,
diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md
index 04cd5387..5e3410fa 100644
--- a/content/client-server-api/modules/push.md
+++ b/content/client-server-api/modules/push.md
@@ -555,7 +555,7 @@ Definition:
 }
 ```
 
-**`.m.rule.contains_display_name`**
+<a id="_m_rule_contains_display_name"/> **`.m.rule.contains_display_name`**
 
 {{< changed-in v="1.7" >}}
 
@@ -624,7 +624,7 @@ Definition:
 }
 ```
 
-**`.m.rule.roomnotif`**
+<a id="_m_rule_roomnotif"/> **`.m.rule.roomnotif`**
 
 {{< changed-in v="1.7" >}}
 
@@ -752,7 +752,7 @@ Definition:
 
 ##### Default Content Rules
 
-**`.m.rule.contains_user_name`**
+<a id="_m_rule_contains_user_name"/> **`.m.rule.contains_user_name`**
 
 {{< changed-in v="1.7" >}}