fix(docs): Fix macro-related flaws in the template files (#28066)

* fixes macro errors * fixes macro errors * fixes macro errors * fixes macro errors * minor updates * fixes markdown errors * adds domxref and escape character --------- Co-authored-by: Brian Thomas Smith <brian@smith.berlin>
mdn · Jul 27, 2023 · dad6b0e · dad6b0e
1 parent e893b03
commit dad6b0e
Show file tree

Hide file tree

Showing 11 changed files with 217 additions and 135 deletions.
diff --git a/...guidelines/page_structures/page_types/api_constructor_subpage_template/index.md b/...guidelines/page_structures/page_types/api_constructor_subpage_template/index.md
@@ -13,7 +13,7 @@ browser-compat: path.to.feature.NameOfTheConstructor
 >
 > **Page front matter:**
 >
-> The frontmatter at the top of the page is used to define "page metadata".
+> The front matter at the top of the page is used to define "page metadata".
 > The values should be updated appropriately for the constructor.
 >
 > ```md
@@ -34,7 +34,7 @@ browser-compat: path.to.feature.NameOfTheConstructor
 >     Format as _NameOfTheParentInterface_**()**.
 >     For example, the [Request()](/en-US/docs/Web/API/Request/Request) constructor has a _title_ of `Request()`.
 > - **slug**
->   - : The end of the URL path after `https://developer.mozilla.org/en-US/docs/`).
+>   - : The end of the URL path after `https://developer.mozilla.org/en-US/docs/`.
 >     This will be formatted like `Web/API/NameOfTheParentInterface/NameOfTheParentInterface`.
 >     Note that the name of the constructor function in the slug omits the parenthesis (it ends in `NameOfTheParentInterface` not `NameOfTheParentInterface()`).
 > - **page-type**
@@ -53,7 +53,7 @@ browser-compat: path.to.feature.NameOfTheConstructor
 >
 > **Top-of-page macros**
 >
-> A number of macro calls appear at the top of the content section (immediately below the page frontmatter).
+> A number of macro calls appear at the top of the content section (immediately below the page front matter).
 > You should update or delete them according to the advice below:
 >
 > - `\{{SeeCompatTable}}` — this generates a **This is an experimental technology** banner that indicates the technology is [experimental](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental).
@@ -67,15 +67,16 @@ browser-compat: path.to.feature.NameOfTheConstructor
 > - `\{{APIRef("GroupDataName")}}` — this generates the left-hand reference sidebar showing quick reference links related to the current page.
 >   For example, every page in the [WebVR API](/en-US/docs/Web/API/WebVR_API) has the same sidebar, which points to the other pages in the API.
 >   To generate the correct sidebar for your API, you need to add a `GroupData` entry to our GitHub repo, and include the entry's name inside the macro call in place of _GroupDataName_.
->   See our [API reference sidebars](/en-US/docs/MDN/Writing_guidelines/Howto/Write_an_API_reference/Sidebars) guide for information on how to do this.
-> - Remember to remove the `\{{MDNSidebar}}` macro when you copy this page.
+>   See our [API reference sidebars](/en-US/docs/MDN/Writing_guidelines/Howto/Write_an_API_reference/Sidebars) guide for information on how to do this. Remember to remove the `\{{MDNSidebar}}` macro when you copy this page.
 >
-> _Remember to remove this whole explanatory note before publishing_
+> Samples of the **Experimental**, **Secure context**, and **Deprecated** banners are shown right after this note block.
+>
+> _Remember to remove this whole explanatory note before publishing._
 
-{{SeeCompatTable}}{{SecureContext_Header}}{{Deprecated_Header}}{{APIRef("GroupDataName")}}
+{{SeeCompatTable}}{{SecureContext_Header}}{{Deprecated_Header}}
 
-The summary paragraph — start by naming the constructor, and saying what it does.
-This should ideally be 1 or 2 short sentences.
+Begin the content on the page with an introductory paragraph — start by naming the constructor and saying what it does.
+This should ideally be one or two short sentences.
 You could copy most of this from the constructor's summary on the corresponding API reference page.
 
 ## Syntax
@@ -93,14 +94,18 @@ Fill in a syntax box, according to the guidance in our [syntax sections](/en-US/
 ### Return value
 
 Include a description of the constructor's return value, including data type and what it represents.
-This is normally just "An instance of the {{domxref("NameOfTheParentInterface")}} object."
+This is normally just "An instance of the `\{{domxref("NameOfTheParentInterface")}}` object."
+
+_To use this macro, remove the backticks and backslash in the markdown file._
 
 ### Exceptions
 
-- Exception1
-  - : Include a list of all the exceptions that the constructor can raise, along with descriptions of how that exception is raised. Include one term and definition for each exception.
-- Exception2
-  - : etc.
+Include a list of all the exceptions that the constructor can raise. Include one term and definition for each exception.
+
+- `Exception1`
+  - : Include descriptions of how the exception is raised.
+- `Exception2`
+  - : Include descriptions of how the exception is raised.
 
 ## Examples
 
@@ -140,15 +145,20 @@ See our guide on how to add [code examples](/en-US/docs/MDN/Writing_guidelines/P
 
 ## Specifications
 
-{{Specifications}}
+`\{{Specifications}}`
+
+_To use this macro, remove the backticks and backslash in the markdown file._
 
 ## Browser compatibility
 
-{{Compat}}
+`\{{Compat}}`
+
+_To use this macro, remove the backticks and backslash in the markdown file._
 
 ## See also
 
 Include links to reference pages and guides related to the current API. For more guidelines, see the [See also section](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide#see_also_section) in the _Writing style guide_.
 
 - link1
 - link2
+- external_link (year)
diff --git a/...iting_guidelines/page_structures/page_types/api_event_subpage_template/index.md b/...iting_guidelines/page_structures/page_types/api_event_subpage_template/index.md
@@ -7,13 +7,13 @@ browser-compat: path.to.feature.NameOfTheEvent_event
 
 {{MDNSidebar}}
 
-> **Note:** _Remove this whole explanatory note before publishing_
+> **Note:** _Remove this whole explanatory note before publishing._
 >
 > ---
 >
 > **Page front matter:**
 >
-> The frontmatter at the top of the page is used to define "page metadata".
+> The front matter at the top of the page is used to define "page metadata".
 > The values should be updated appropriately for the particular event.
 >
 > ```md
@@ -66,8 +66,9 @@ browser-compat: path.to.feature.NameOfTheEvent_event
 > - `\{{APIRef("GroupDataName")}}` — this generates the left-hand reference sidebar showing quick reference links related to the current page.
 >   For example, every page in the [WebVR API](/en-US/docs/Web/API/WebVR_API) has the same sidebar, which points to the other pages in the API.
 >   To generate the correct sidebar for your API, you need to add a `GroupData` entry to our GitHub repo, and include the entry's name inside the macro call in place of _GroupDataName_.
->   See our [API reference sidebars](/en-US/docs/MDN/Writing_guidelines/Howto/Write_an_API_reference/Sidebars) guide for information on how to do this.
-> - Remember to remove the `\{{MDNSidebar}}` macro when you copy this page.
+>   See our [API reference sidebars](/en-US/docs/MDN/Writing_guidelines/Howto/Write_an_API_reference/Sidebars) guide for information on how to do this. Remember to remove the `\{{MDNSidebar}}` macro when you copy this page.
+>
+> Samples of the **Experimental**, **Secure context**, and **Deprecated** banners are shown right after this note block.
 >
 > ---
 >
@@ -79,12 +80,12 @@ browser-compat: path.to.feature.NameOfTheEvent_event
 > If the parent object does not have an _Events_ section, then add one.
 > If this is a new "class" of event, then you should add link to this section of the parent from the [Event reference](/en-US/docs/Web/Events).
 >
-> _Remember to remove this whole explanatory note before publishing_
+> _Remember to remove this whole explanatory note before publishing._
 
-{{SeeCompatTable}}{{SecureContext_Header}}{{Deprecated_Header}}{{APIRef("GroupDataName")}}
+{{SeeCompatTable}}{{SecureContext_Header}}{{Deprecated_Header}}
 
-The summary paragraph — start by naming the event, saying what interface it is part of, and saying what it does.
-This should ideally be 1 or 2 short sentences.
+Begin the content on the page with an introductory paragraph — start by naming the event, saying what interface it is part of, and saying what it does.
+This should ideally be one or two short sentences.
 You could copy most of this from the property's summary on the corresponding API reference page.
 
 ## Syntax
@@ -171,15 +172,20 @@ See our guide on how to add [code examples](/en-US/docs/MDN/Writing_guidelines/P
 
 ## Specifications
 
-{{Specifications}}
+`\{{Specifications}}`
+
+_To use this macro, remove the backticks and backslash in the markdown file._
 
 ## Browser compatibility
 
-{{Compat}}
+`\{{Compat}}`
+
+_To use this macro, remove the backticks and backslash in the markdown file._
 
 ## See also
 
 Include links to reference pages and guides related to the current API. For more guidelines, see the [See also section](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide#see_also_section) in the _Writing style guide_.
 
 - link1
 - link2
+- external_link (year)
diff --git a/...riting_guidelines/page_structures/page_types/api_landing_page_template/index.md b/...riting_guidelines/page_structures/page_types/api_landing_page_template/index.md
@@ -12,7 +12,7 @@ page-type: mdn-writing-guide
 >
 > **Page front matter:**
 >
-> The frontmatter at the top of the page is used to define "page metadata".
+> The front matter at the top of the page is used to define "page metadata".
 > The values should be updated appropriately for the particular interface.
 >
 > ```md
@@ -44,7 +44,7 @@ page-type: mdn-writing-guide
 >
 > **Top-of-page macros**
 >
-> A number of macro calls appear at the top of the content section (immediately below the page frontmatter).
+> A number of macro calls appear at the top of the content section (immediately below the page front matter).
 > You should update or delete them according to the advice below:
 >
 > - `\{{SeeCompatTable}}` — this generates a **This is an experimental technology** banner that indicates the technology is [experimental](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental).
@@ -85,10 +85,9 @@ page-type: mdn-writing-guide
 >
 > _Remember to remove this whole explanatory note before publishing_
 
-{{APIRef("GroupDataName")}}{{securecontext_header}}
+{{securecontext_header}}
 
-The summary paragraph — start by naming the API, and saying what it is used for.
-This should ideally be 1 or 2 short sentences.
+Begin the content on the page with an introductory paragraph — start by naming the API and saying what it does. This should ideally be one or two short sentences.
 
 ## Concepts and usage
 
@@ -103,7 +102,9 @@ To help improve content discoverability and {{Glossary("SEO")}}, keep the follow
 
 ## Interfaces
 
-- {{domxref("NameOfTheInterface")}}
+_To use the [domxref macro](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros#linking_to_pages_in_references), remove the backticks and backslash in the markdown file._
+
+- `\{{domxref("NameOfTheInterface")}}`
   - : Include a brief description of the interface and what it does here.
     Include one term and definition for each interface or dictionary.
 
@@ -113,13 +114,13 @@ The _name of interface_ extends the following APIs, adding the listed features.
 
 #### Interface 1
 
-- {{domxref("addition1")}}
+- `\{{domxref("addition1")}}`
   - : Description of the feature of Interface#1 that is added to that API by the API you are currently documenting.
     One \*term and definition for each feature. If this API doesn't extend any other interfaces, you can delete these sections.
 
 #### Interface 2
 
-- {{domxref("addition1")}}
+- `\{{domxref("addition1")}}`
   - : Description of the feature of Interface#2 that is added to that API by the API you are currently documenting, etc.
 
 ## Examples
@@ -162,19 +163,24 @@ See our guide on how to add [code examples](/en-US/docs/MDN/Writing_guidelines/P
 
 ## Specifications
 
-{{Specifications("path.to.feature.Interface_1")}}
+`\{{Specifications("path.to.feature.Interface_1")}}`
+
+`\{{Specifications("path.to.feature.Interface_2")}}`
 
-{{Specifications("path.to.feature.Interface_2")}}
+_To use this macro, remove the backticks and backslash in the markdown file._
 
 ## Browser compatibility
 
-{{Compat("path.to.feature.Interface_1")}}
+`\{{Compat("path.to.feature.Interface_1")}}`
+
+`\{{Compat("path.to.feature.Interface_2")}}`
 
-{{Compat("path.to.feature.Interface_2")}}
+_To use this macro, remove the backticks and backslash in the markdown file._
 
 ## See also
 
 Include links to reference pages and guides related to the current API. For more guidelines, see the [See also section](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide#see_also_section) in the _Writing style guide_.
 
 - link1
 - link2
+- external_link (year)
diff --git a/...ting_guidelines/page_structures/page_types/api_method_subpage_template/index.md b/...ting_guidelines/page_structures/page_types/api_method_subpage_template/index.md
@@ -7,13 +7,13 @@ browser-compat: path.to.feature.NameOfTheMethod
 
 {{MDNSidebar}}
 
-> **Note:** _Remove this whole explanatory note before publishing_
+> **Note:** _Remove this whole explanatory note before publishing._
 >
 > ---
 >
 > **Page front matter:**
 >
-> The frontmatter at the top of the page is used to define "page metadata".
+> The front matter at the top of the page is used to define "page metadata".
 > The values should be updated appropriately for the particular method.
 >
 > ```md
@@ -58,7 +58,7 @@ browser-compat: path.to.feature.NameOfTheMethod
 >
 > **Top-of-page macros**
 >
-> A number of macro calls appear at the top of the content section (immediately below the page frontmatter).
+> A number of macro calls appear at the top of the content section (immediately below the page front matter).
 > You should update or delete them according to the advice below:
 >
 > - `\{{SeeCompatTable}}` — this generates a **This is an experimental technology** banner that indicates the technology is [experimental](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental).
@@ -72,15 +72,16 @@ browser-compat: path.to.feature.NameOfTheMethod
 > - `\{{APIRef("GroupDataName")}}` — this generates the left-hand reference sidebar showing quick reference links related to the current page.
 >   For example, every page in the [WebVR API](/en-US/docs/Web/API/WebVR_API) has the same sidebar, which points to the other pages in the API.
 >   To generate the correct sidebar for your API, you need to add a `GroupData` entry to our GitHub repo, and include the entry's name inside the macro call in place of _GroupDataName_.
->   See our [API reference sidebars](/en-US/docs/MDN/Writing_guidelines/Howto/Write_an_API_reference/Sidebars) guide for information on how to do this.
-> - Remember to remove the `\{{MDNSidebar}}` macro when you copy this page.
+>   See our [API reference sidebars](/en-US/docs/MDN/Writing_guidelines/Howto/Write_an_API_reference/Sidebars) guide for information on how to do this. Remember to remove the `\{{MDNSidebar}}` macro when you copy this page.
 >
-> _Remember to remove this whole explanatory note before publishing_
+> Samples of the **Experimental**, **Secure context**, and **Deprecated** banners are shown right after this note block.
+>
+> _Remember to remove this whole explanatory note before publishing._
 
-{{APIRef("GroupDataName")}}{{SeeCompatTable}}{{SecureContext_header}}{{Deprecated_Header}}
+{{SeeCompatTable}}{{SecureContext_header}}{{Deprecated_Header}}
 
-The summary paragraph — start by naming the method, saying what interface it is part of, and saying what it does.
-This should ideally be 1 or 2 short sentences. You could copy most of this from the method's summary on the corresponding API reference page.
+Begin the content on the page with an introductory paragraph — start by naming the method, saying what interface it is part of, and saying what it does.
+This should ideally be one or two short sentences. You could copy most of this from the method's summary on the corresponding API reference page.
 
 ## Syntax
 
@@ -103,10 +104,12 @@ If the method doesn't return anything, just put "None ({{jsxref('undefined')}}).
 
 ### Exceptions
 
+Include a list of all the exceptions that the constructor can raise. Include one term and definition for each exception.
+
 - `Exception1`
-  - : Include a list of all the exceptions that the method can raise, along with descriptions of how that exception is raised. Include one term and definition for each exception.
+  - : Include descriptions of how the exception is raised.
 - `Exception2`
-  - : etc.
+  - : Include descriptions of how the exception is raised.
 
 Note that we have two kinds of exceptions: {{domxref("DOMException")}} objects and regular JavaScript exceptions, like {{jsxref("TypeError")}} and {{jsxref("RangeError")}}. A web developer needs to know:
 
@@ -162,15 +165,20 @@ See our guide on how to add [code examples](/en-US/docs/MDN/Writing_guidelines/P
 
 ## Specifications
 
-{{Specifications}}
+`\{{Specifications}}`
+
+_To use this macro, remove the backticks and backslash in the markdown file._
 
 ## Browser compatibility
 
-{{Compat}}
+`\{{Compat}}`
+
+_To use this macro, remove the backticks and backslash in the markdown file._
 
 ## See also
 
 Include links to reference pages and guides related to the current API. For more guidelines, see the [See also section](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide#see_also_section) in the _Writing style guide_.
 
 - link1
 - link2
+- external_link (year)