From 5b71d5feccf62b03311b7232d3bb965b7830868b Mon Sep 17 00:00:00 2001
From: Will <>
Date: Wed, 21 Apr 2021 09:28:16 -0700
Subject: [PATCH 1/8] Add a section on notes and warnings
---
.../mdn/contribute/markdown_in_mdn/index.html | 103 +++++++++++++++++-
1 file changed, 102 insertions(+), 1 deletion(-)
diff --git a/files/en-us/mdn/contribute/markdown_in_mdn/index.html b/files/en-us/mdn/contribute/markdown_in_mdn/index.html
index 6b3d213796af5dc..c71f9f48a0ef5fb 100644
--- a/files/en-us/mdn/contribute/markdown_in_mdn/index.html
+++ b/files/en-us/mdn/contribute/markdown_in_mdn/index.html
@@ -113,7 +113,108 @@ Example code blocks
```
-Notes and warnings
+Notes, warnings, and callouts
+
+Sometimes writers want to call special attention to some piece of content. To do this, they will use a GFM blockquote with a special first paragraph. There are three types of these: notes, warnings, and callouts:
+
+Notes
+
+To write a note, an author creates a GFM blockquote whose first paragraph starts with "**Note:**":
+
+
+> **Note:** This is how you write a note.
+>
+> It can have multiple lines.
+
+
+This will produce the following HTML:
+
+
+<div class="notecard note">
+ <p><strong>Note:</strong> This is how you write a note.</p>
+ <p>It can have multiple paragraphs.</p>
+</div>
+
+
+This HTML will be rendered as a highlighted box, like:
+
+
+
Note: This is how you write a note.
+
It can have multiple paragraphs.
+
Warnings
+
+To write a warning, an author creates a GFM blockquote whose first paragraph starts with "**Warning:**":
+
+
+> **Warning: This is how you write a warning.
+>
+> It can have multiple lines.
+
+
+This will produce the following HTML:
+
+
+<div class="notecard warning">
+ <p><strong>Warning:</strong> This is how you write a warning.</p>
+ <p>It can have multiple paragraphs.</p>
+</div>
+
+
+This HTML will be rendered as a highlighted box, like:
+
+
+
Warning: This is how you write a warning.
+
It can have multiple paragraphs.
+
Callouts
+
+To write a callout, an author creates a GFM blockquote whose first paragraph starts with "**Callout:**":
+
+
+> **Callout:** **This is how you write a callout**.
+>
+> It can have multiple lines.
+
+
+This will produce the following HTML:
+
+
+<div class="callout">
+ <p><strong>This is how you write a callout.</strong></p>
+ <p>It can have multiple paragraphs.</p>
+</div>
+
+
+This HTML will be rendered as a highlighted box, like:
+
+
+
This is how you write a callout.
+
It can have multiple paragraphs.
+
Note that while notes and warnings keep the magic word in the output, callouts don't. This means that they are a good choice when an author wants to use a custom title.
+
+Notes, warnings, and translations
+
+Because the text "Note:" or "Warning:" also appears in the rendered output, it has to be sensitive to translations. In practice this means that every locale supported by MDN must supply its own translation of these strings, and the platform must recognize them as indicating that the construct needs special treatment.
+
+For example, if we want to use "Warnung" for "Warning" in German, then in German pages we would write:
+
+
+> Warnung: So schreibt man eine Warnung.
+
+
+...and this will produce:
+
+
+<div class="notecard warning">
+ <p><strong>Warnung:</strong> So schreibt man eine Warnung.</p>
+</div>
+
Definition lists
From 576c89a6c22814fa22cf045da97c6f3ecac11117 Mon Sep 17 00:00:00 2001
From: wbamberg
Date: Thu, 22 Apr 2021 16:00:51 -0700
Subject: [PATCH 2/8] Update
files/en-us/mdn/contribute/markdown_in_mdn/index.html
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Co-authored-by: André Jaenisch
---
files/en-us/mdn/contribute/markdown_in_mdn/index.html | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/files/en-us/mdn/contribute/markdown_in_mdn/index.html b/files/en-us/mdn/contribute/markdown_in_mdn/index.html
index c71f9f48a0ef5fb..3d6e7d06203b33a 100644
--- a/files/en-us/mdn/contribute/markdown_in_mdn/index.html
+++ b/files/en-us/mdn/contribute/markdown_in_mdn/index.html
@@ -115,7 +115,7 @@ Example code blocks
Notes, warnings, and callouts
-Sometimes writers want to call special attention to some piece of content. To do this, they will use a GFM blockquote with a special first paragraph. There are three types of these: notes, warnings, and callouts:
+Sometimes writers want to call special attention to some piece of content. To do this, they will use a GFM blockquote with a special first paragraph. There are three types of these: notes, warnings, and callouts.
Notes
From 0cb16191e152b167e4b517569f3d50de0845cb32 Mon Sep 17 00:00:00 2001
From: wbamberg
Date: Thu, 22 Apr 2021 16:01:17 -0700
Subject: [PATCH 3/8] Update
files/en-us/mdn/contribute/markdown_in_mdn/index.html
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Co-authored-by: André Jaenisch
---
files/en-us/mdn/contribute/markdown_in_mdn/index.html | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/files/en-us/mdn/contribute/markdown_in_mdn/index.html b/files/en-us/mdn/contribute/markdown_in_mdn/index.html
index 3d6e7d06203b33a..dc9dcd18695efe6 100644
--- a/files/en-us/mdn/contribute/markdown_in_mdn/index.html
+++ b/files/en-us/mdn/contribute/markdown_in_mdn/index.html
@@ -119,7 +119,7 @@ Notes, warnings, and callouts
Notes
-To write a note, an author creates a GFM blockquote whose first paragraph starts with "**Note:**":
+To write a note, an author creates a GFM blockquote whose first paragraph starts with "**Note:**".
> **Note:** This is how you write a note.
From c7507904c9cc7f94a316021b8129b912cb46ecbb Mon Sep 17 00:00:00 2001
From: wbamberg
Date: Thu, 22 Apr 2021 16:17:00 -0700
Subject: [PATCH 4/8] Update
files/en-us/mdn/contribute/markdown_in_mdn/index.html
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Co-authored-by: André Jaenisch
---
files/en-us/mdn/contribute/markdown_in_mdn/index.html | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/files/en-us/mdn/contribute/markdown_in_mdn/index.html b/files/en-us/mdn/contribute/markdown_in_mdn/index.html
index dc9dcd18695efe6..1191bd42f759bb0 100644
--- a/files/en-us/mdn/contribute/markdown_in_mdn/index.html
+++ b/files/en-us/mdn/contribute/markdown_in_mdn/index.html
@@ -132,7 +132,7 @@ Notes
<div class="notecard note">
<p><strong>Note:</strong> This is how you write a note.</p>
- <p>It can have multiple paragraphs.</p>
+ <p>It can have multiple lines.</p>
</div>
From b53322ed04789aef5747b9dacc05b09ec604bd14 Mon Sep 17 00:00:00 2001
From: wbamberg
Date: Thu, 22 Apr 2021 16:17:14 -0700
Subject: [PATCH 5/8] Update
files/en-us/mdn/contribute/markdown_in_mdn/index.html
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Co-authored-by: André Jaenisch
---
files/en-us/mdn/contribute/markdown_in_mdn/index.html | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/files/en-us/mdn/contribute/markdown_in_mdn/index.html b/files/en-us/mdn/contribute/markdown_in_mdn/index.html
index 1191bd42f759bb0..060fd87c44c25d7 100644
--- a/files/en-us/mdn/contribute/markdown_in_mdn/index.html
+++ b/files/en-us/mdn/contribute/markdown_in_mdn/index.html
@@ -140,7 +140,7 @@ Notes
Note: This is how you write a note.
-
It can have multiple paragraphs.
+
It can have multiple lines.
Warnings
From 63441b30428e971c70a8405356f2a2a72a679ae8 Mon Sep 17 00:00:00 2001
From: wbamberg
Date: Thu, 22 Apr 2021 16:17:21 -0700
Subject: [PATCH 6/8] Update
files/en-us/mdn/contribute/markdown_in_mdn/index.html
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Co-authored-by: André Jaenisch
---
files/en-us/mdn/contribute/markdown_in_mdn/index.html | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/files/en-us/mdn/contribute/markdown_in_mdn/index.html b/files/en-us/mdn/contribute/markdown_in_mdn/index.html
index 060fd87c44c25d7..736b5ca9d9fdb94 100644
--- a/files/en-us/mdn/contribute/markdown_in_mdn/index.html
+++ b/files/en-us/mdn/contribute/markdown_in_mdn/index.html
@@ -177,7 +177,7 @@ Callouts
> **Callout:** **This is how you write a callout**.
>
-> It can have multiple lines.
+> It can have multiple paragaphs.
This will produce the following HTML:
From e3d8d33e42bb296e45bbea002f5dc0ce787fa96e Mon Sep 17 00:00:00 2001
From: wbamberg
Date: Thu, 22 Apr 2021 16:17:35 -0700
Subject: [PATCH 7/8] Update
files/en-us/mdn/contribute/markdown_in_mdn/index.html
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Co-authored-by: André Jaenisch
---
files/en-us/mdn/contribute/markdown_in_mdn/index.html | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/files/en-us/mdn/contribute/markdown_in_mdn/index.html b/files/en-us/mdn/contribute/markdown_in_mdn/index.html
index 736b5ca9d9fdb94..fb924b97e7edaa5 100644
--- a/files/en-us/mdn/contribute/markdown_in_mdn/index.html
+++ b/files/en-us/mdn/contribute/markdown_in_mdn/index.html
@@ -150,7 +150,7 @@ Warnings
> **Warning: This is how you write a warning.
>
-> It can have multiple lines.
+> It can have multiple paragraphs.
This will produce the following HTML:
From e70a2bb40765ade3c27967f47a57d3b4c05921d5 Mon Sep 17 00:00:00 2001
From: Will <>
Date: Wed, 28 Apr 2021 17:07:27 -0700
Subject: [PATCH 8/8] Update note syntax description
---
.../mdn/contribute/markdown_in_mdn/index.html | 70 +++++++++++++++----
1 file changed, 56 insertions(+), 14 deletions(-)
diff --git a/files/en-us/mdn/contribute/markdown_in_mdn/index.html b/files/en-us/mdn/contribute/markdown_in_mdn/index.html
index dc9dcd18695efe6..ba1b64b16460917 100644
--- a/files/en-us/mdn/contribute/markdown_in_mdn/index.html
+++ b/files/en-us/mdn/contribute/markdown_in_mdn/index.html
@@ -117,9 +117,25 @@ Notes, warnings, and callouts
Sometimes writers want to call special attention to some piece of content. To do this, they will use a GFM blockquote with a special first paragraph. There are three types of these: notes, warnings, and callouts.
-Notes
+
+ - To add a note, create a GFM blockquote whose first paragraph starts with
**Note:**.
+ - To add a warning, create a GFM blockquote whose first paragraph starts with
**Warning:**.
+ - To add a callout, create a GFM blockquote whose first paragraph starts with
**Callout:**.
+
+
+Notes and warnings will render the Note: or Warning: text in the output, while callouts will not. This makes callouts a good choice when an author wants to provide a custom title.
+
+Processing of the markup works on the AST it produces, not on the exact characters provided. This means that providing <strong>Note:</strong> will also generate a note. However, the Markdown syntax is required as a matter of style.
+
+Multiple lines are produced by an empty block quote line in the same way as normal paragraphs. Further, multiple lines without a space are also treated like normal markdown lines, and concatenated.
+
+The blockquote can contain code blocks or other block elements.
+
+Because the text "Note:" or "Warning:" also appears in the rendered output, it has to be sensitive to translations. In practice this means that every locale supported by MDN must supply its own translation of these strings, and the platform must recognize them as indicating that the construct needs special treatment.
+
+Examples
-To write a note, an author creates a GFM blockquote whose first paragraph starts with "**Note:**".
+Note
> **Note:** This is how you write a note.
@@ -143,9 +159,7 @@ Notes
It can have multiple paragraphs.
-Warnings
-
-To write a warning, an author creates a GFM blockquote whose first paragraph starts with "**Warning:**":
+Warnings
> **Warning: This is how you write a warning.
@@ -169,10 +183,7 @@ Warnings
It can have multiple paragraphs.
-
-Callouts
-
-To write a callout, an author creates a GFM blockquote whose first paragraph starts with "**Callout:**":
+Callouts
> **Callout:** **This is how you write a callout**.
@@ -196,11 +207,7 @@ Callouts
It can have multiple paragraphs.
-Note that while notes and warnings keep the magic word in the output, callouts don't. This means that they are a good choice when an author wants to use a custom title.
-
-Notes, warnings, and translations
-
-Because the text "Note:" or "Warning:" also appears in the rendered output, it has to be sensitive to translations. In practice this means that every locale supported by MDN must supply its own translation of these strings, and the platform must recognize them as indicating that the construct needs special treatment.
+Translated warning
For example, if we want to use "Warnung" for "Warning" in German, then in German pages we would write:
@@ -216,6 +223,41 @@ Notes, warnings, and translations
</div>
+Note containing a code block
+
+This example contains a code block.
+
+
+> **Note:** This is how you write a note.
+>
+> It can contain code blocks.
+>
+> ```js
+> const s = "I'm in a code block";
+> ```
+> Like that.
+
+
+This will produce the following HTML:
+
+
+<div class="notecard note">
+ <p><strong>Note:</strong> This is how you write a note.</p>
+ <p>It can contain code blocks.</p>
+ <pre class="brush: js">const s = "I'm in a code block";</pre>
+ <p>Like that.</p>
+</div>
+
+
+This HTML will be rendered as with a code block, like:
+
+
+
Note: This is how you write a note.
+
It can contain code blocks.
+
const s = "I'm in a code block";
+
Like that.
+
Definition lists
Tables