diff --git a/help/format-your-message-using-markdown.md b/help/format-your-message-using-markdown.md
index e72e10c967..4bcabe3cfc 100644
--- a/help/format-your-message-using-markdown.md
+++ b/help/format-your-message-using-markdown.md
@@ -22,7 +22,7 @@ whenever you need a reminder of the formatting syntax below.
 * [Quotes](#quotes)
 * [Spoilers](#spoilers)
 * [Emoji and emoticons](#emoji-and-emoticons)
-* [Mentions](#mentions)
+* [Mention a user or group](#mention-a-user-or-group)
 * [Status messages](#status-messages)
 * [Global times](#global-times)
 * [Tables](#tables)
@@ -86,21 +86,11 @@ whenever you need a reminder of the formatting syntax below.
 
 {!emoji-and-emoticons-examples.md!}
 
-## Mentions
+## Mention a user or group
 
-Learn more about mentions [here](/help/mention-a-user-or-group).
+{!mentions-intro.md!}
 
-```
-Users: @**Polonius** or @**aaron|26** or @**|26** (two asterisks)
-User group: @*support team* (one asterisk)
-Silent mention: @_**Polonius** or @_**|26** (@_ instead of @)
-```
-
-The variants with numbers use user IDs, and are intended for
-disambiguation (if multiple users have the same name) and bots (for
-the variant that only contains the user ID).
-
-![Markdown mentions](/static/images/help/markdown-mentions.png)
+{!mentions-examples.md!}
 
 ## Status messages
 
diff --git a/help/include/mentions-examples.md b/help/include/mentions-examples.md
new file mode 100644
index 0000000000..50da52c329
--- /dev/null
+++ b/help/include/mentions-examples.md
@@ -0,0 +1,17 @@
+### What you type
+
+```
+Users: @**Bo Lin** or @**Ariella Drake|26** (two `*`)
+User group: @*support team* (one `*`)
+Silent mention: @_**Bo Lin** or @_**Ariella Drake|26** (`@_` instead of `@`)
+```
+
+!!! tip ""
+
+    A `|` followed by a user ID is inserted automatically when you select a
+    user from the typeahead suggestions, if there are two users with the same
+    name in the organization.
+
+### What it looks like
+
+![Markdown mentions](/static/images/help/markdown-mentions.png)
diff --git a/help/include/mentions-intro.md b/help/include/mentions-intro.md
new file mode 100644
index 0000000000..2615ad7126
--- /dev/null
+++ b/help/include/mentions-intro.md
@@ -0,0 +1,5 @@
+You can mention a team member or [user group](/help/user-groups) to call their
+attention to a message. Mentions follow the same [notification
+settings](/help/dm-mention-alert-notifications) as direct messages and alert
+words. A [silent mention](/help/mention-a-user-or-group#silently-mention-a-user)
+allows you to refer to a user without triggering a notification.
diff --git a/help/mention-a-user-or-group.md b/help/mention-a-user-or-group.md
index f965c6099f..babc3285ee 100644
--- a/help/mention-a-user-or-group.md
+++ b/help/mention-a-user-or-group.md
@@ -1,9 +1,6 @@
 # Mention a user or group
 
-You can mention a team member or [user group](/help/user-groups) to call their attention to a
-message. Mentions follow the same
-[notification settings](/help/dm-mention-alert-notifications) as direct
-messages and alert words.
+{!mentions-intro.md!}
 
 ## Mention a user or group
 
@@ -70,8 +67,13 @@ wildcard mentions, either
 [globally](/help/dm-mention-alert-notifications) or for [individual
 streams](/help/stream-notifications).
 
+## Examples
+
+{!mentions-examples.md!}
+
 ## Related articles
 
+* [Message formatting](/help/format-your-message-using-markdown)
 * [Restrict wildcard mentions](/help/restrict-wildcard-mentions)
 * [Quote and reply](/help/quote-and-reply)
 * [View your mentions](/help/view-your-mentions)
diff --git a/static/images/help/markdown-mentions.png b/static/images/help/markdown-mentions.png
index ba0a35ee79..2dbaa55b20 100644
Binary files a/static/images/help/markdown-mentions.png and b/static/images/help/markdown-mentions.png differ