From 255add92b9bf7d80758f392e6892be411fb438af Mon Sep 17 00:00:00 2001
From: Marcel Amirault <mamirault@gitlab.com>
Date: Wed, 17 Dec 2025 11:20:37 +0900
Subject: [PATCH 1/2] Add notes on when to not translate

This file has special translation rules, so many code examples
are translated too. But we should not translate when a screenshot
is presenting the rendered view, as they'll be out of sync
---
 doc/user/markdown.md | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/doc/user/markdown.md b/doc/user/markdown.md
index fb7116e8e466ef..7f919d4cda6f76 100644
--- a/doc/user/markdown.md
+++ b/doc/user/markdown.md
@@ -172,6 +172,11 @@ The IDs are generated from the content of the heading according to the following
 
 Example:
 
+<!--
+Translation note: DO NOT TRANSLATE this example. The example must stay untranslated
+to stay in sync with the example link IDs.
+-->
+
 ```markdown
 # This heading has spaces in it
 ## This heading has a :thumbsup: in it
@@ -331,6 +336,11 @@ With inline diff tags, you can display `{+ additions +}` or `[- deletions -]`.
 
 The wrapping tags can be either curly braces or square brackets:
 
+<!--
+Translation note: DO NOT TRANSLATE this example. The example must stay untranslated
+to stay in sync with the image.
+-->
+
 ```markdown
 - {+ addition 1 +}
 - [+ addition 2 +]
@@ -354,6 +364,11 @@ However, you cannot mix the wrapping tags:
 Diff highlighting doesn't work with `` `inline code` ``. If your text includes backticks (`` ` ``), [escape](#escape-characters)
 each backtick with a backslash ` \ `:
 
+<!--
+Translation note: DO NOT TRANSLATE this example. The example must stay untranslated
+to stay in sync with the image.
+-->
+
 ```markdown
 - {+ Just regular text +}
 - {+ Text with `backticks` inside +}
@@ -621,6 +636,11 @@ in an issue, merge request, epic, or comment has no effect.
 
 To create a task list, follow the format of an ordered or unordered list:
 
+<!--
+Translation note: DO NOT TRANSLATE this example. The example must stay untranslated
+to stay in sync with the image.
+-->
+
 ```markdown
 - [x] Completed task
 - [~] Inapplicable task
@@ -1576,6 +1596,11 @@ is rendered inline with the text.
 Math written between double dollar signs (`$$...$$`) or in a [code block](#code-spans-and-blocks) with
 the language declared as `math` is rendered on a separate line:
 
+<!--
+Translation note: DO NOT TRANSLATE this example. The example must stay untranslated
+to stay in sync with the image.
+-->
+
 `````markdown
 This math is inline: $`a^2+b^2=c^2`$.
 
@@ -1640,6 +1665,11 @@ For more information, see [issue 359077](https://gitlab.com/gitlab-org/gitlab/-/
 
 {{< /alert >}}
 
+<!--
+Translation note: DO NOT TRANSLATE this example. The example must stay untranslated
+to stay in sync with the image.
+-->
+
 ```markdown
 This is an intro sentence to my wiki page.
 
@@ -1670,6 +1700,11 @@ You can use alerts in any text box that supports Markdown.
 
 You can use the following types of alerts:
 
+<!--
+Translation note: DO NOT TRANSLATE any examples in this section. The examples must stay untranslated
+to stay in sync with the image.
+-->
+
 - Note: information that users should take into account, even when skimming:
 
   ```markdown
-- 
GitLab


From a31d5924a3476977068ba47fb1bf0f6e5e4465d0 Mon Sep 17 00:00:00 2001
From: Marcel Amirault <mamirault@gitlab.com>
Date: Wed, 17 Dec 2025 12:36:51 +0900
Subject: [PATCH 2/2] Apply 1 suggestion(s) to 1 file(s)

---
 doc/user/markdown.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/doc/user/markdown.md b/doc/user/markdown.md
index 7f919d4cda6f76..42997590c5d0d7 100644
--- a/doc/user/markdown.md
+++ b/doc/user/markdown.md
@@ -296,6 +296,11 @@ dealing with code and names that often appear with multiple underscores.
 GitLab Flavored Markdown ignores multiple underlines in words,
 to allow better rendering of Markdown documents discussing code:
 
+<!--
+Translation note: DO NOT TRANSLATE these examples or the rendered versions.
+The mid-word emphasis examples do not work in all languages and must stay in English to render correctly.
+-->
+
 ```markdown
 perform_complicated_task
 
-- 
GitLab