diff --git a/files/en-us/mdn/writing_guidelines/experimental_deprecated_obsolete/index.md b/files/en-us/mdn/writing_guidelines/experimental_deprecated_obsolete/index.md index 6d0f31120892518..4eb35bdf471284e 100644 --- a/files/en-us/mdn/writing_guidelines/experimental_deprecated_obsolete/index.md +++ b/files/en-us/mdn/writing_guidelines/experimental_deprecated_obsolete/index.md @@ -20,7 +20,7 @@ For a technology marked **experimental**, one or more of the following condition - It is only supported through configuration changes such as preferences or flags, regardless of the number of supported rendering engines. - Its defining specification is likely to change significantly in backwards-incompatible ways (i.e., it may break existing code that relies on the feature). -> **Note:** A feature that is only released on one rendering engine is still considered experimental even if it is available on preview builds of other rendering engines (or by setting a preference or flag). +> **Note:** A feature released only on one rendering engine is still considered experimental even if it is available on preview builds of other rendering engines (or by setting a preference or flag). The **experimental** status of a technology may expire if one or more of the following conditions is met: @@ -72,14 +72,7 @@ If the item was _never_ implemented in a release version of _any_ browser, not e If the item was implemented in any release version of any one or more browsers but _only_ behind a preference or a flag, do not delete the item from the documentation immediately. Instead, mark the item as **deprecated** as follows: -- If the item has any documentation pages describing only that one item (such as {{domxref("RTCPeerConnection.close()")}}), add the [`deprecated_header`](https://github.com/mdn/yari/blob/main/kumascript/macros/Deprecated_Header.ejs) macro to the top of the page and add the following `status:` front-matter entry: - - ```yaml - status: - - deprecated - ``` - -- On the overview page for the element, interface, or API, find the list of items that includes the item that's been removed from the specification and add the [`deprecated_inline`](https://github.com/mdn/yari/blob/main/kumascript/macros/Deprecated_Inline.ejs) macro after the item's name in that list. +- Update the item's status data in the browser-compat-data repository by [submitting a pull request](https://github.com/mdn/browser-compat-data/blob/main/docs/contributing.md#updating-the-compat-data). - Search the informative text of the overview page for that interface, element, etc., for any references to the removed item. Add warning boxes in appropriate places with text along the lines of "\[item] has been removed from the specification and will be removed from browsers soon. See \[link to page] for a new way to do this." - Similarly, look for any discussion of the item in the guides and tutorials about the relevant API or technology. Add similar warnings. - Search MDN Web Docs for references to the removed item, in case there are discussions elsewhere. Add similar warning boxes there as well. @@ -90,14 +83,7 @@ If the item was implemented in any release version of any one or more browsers b If the item was implemented in one or more release builds of browsers without requiring a preference or a flag, mark the item as **deprecated**, as follows: -- If the item has any documentation pages describing only that one item (such as {{domxref("RTCPeerConnection.close()")}}), add the [`deprecated_header`](https://github.com/mdn/yari/blob/main/kumascript/macros/Deprecated_Header.ejs) macro to the top of the page and add the following `status:` front-matter entry: - - ```yaml - status: - - deprecated - ``` - -- On the overview page for the element, interface, or API, find the list of items that includes the item that's been removed from the specification and add the [`deprecated_inline`](https://github.com/mdn/yari/blob/main/kumascript/macros/Deprecated_Inline.ejs) macro after the item's name in that list. +- Update the item's status data in the browser-compat-data repository by [submitting a pull request](https://github.com/mdn/browser-compat-data/blob/main/docs/contributing.md#updating-the-compat-data). - Search the informative text of the overview page for that interface, element, etc., for any references to the removed item. Add warning boxes in appropriate places with text along the lines of "\[item] has been removed from the specification and is deprecated. It may be removed from browsers in the future, so you should not use it. See \[link to page] for a new way to do this." - Similarly, look for any discussion of the item in the guides and tutorials about the relevant API or technology. Add similar warnings. - Search MDN Web Docs for references to the removed item, in case there are discussions elsewhere. Add similar warning boxes there as well. @@ -117,3 +103,7 @@ For example, as of Jan 2019, the [`inputmode`](/en-US/docs/Web/HTML/Global_attri > **Warning:** Specification conflict: The WHATWG specification lists [`inputmode`](https://html.spec.whatwg.org/multipage/interaction.html#attr-inputmode) and modern browsers are working towards supporting it. > The [W3C HTML 5.2 spec](https://html.spec.whatwg.org/multipage/index.html#contents), however, no longer lists it (i.e. marks it as obsolete). > You should consider the WHATWG definition as correct, until a consensus is reached. + +## See also + +- [Feature status macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status) diff --git a/files/en-us/mdn/writing_guidelines/howto/write_an_api_reference/index.md b/files/en-us/mdn/writing_guidelines/howto/write_an_api_reference/index.md index 953c5e4064e3db8..6065d08f519fdb4 100644 --- a/files/en-us/mdn/writing_guidelines/howto/write_an_api_reference/index.md +++ b/files/en-us/mdn/writing_guidelines/howto/write_an_api_reference/index.md @@ -68,7 +68,7 @@ Before you start you should write down a list of all the pages you should create #### Overview pages -A single API overview page is used to describe the role of the API, its top-level interfaces, related features contained in other interfaces, and other high level details. +A single API overview page is used to describe the role of the API, its top-level interfaces, related features contained in other interfaces, and other high-level details. Its name and slug should be the name of the API plus "API" on the end. It is placed at the top level of the API reference, as a child of [https://developer.mozilla.org/en-US/docs/Web/API](/en-US/docs/Web/API). Example: @@ -107,7 +107,7 @@ Examples: #### Constructor pages -Each interface has 0 or 1 constructors, documented on a subpage of the interface's page. It describes the purpose of the constructor and shows what its syntax looks like, usage examples, browser compatibility information, etc. Its slug is the name of the constructor, which is exactly the same as the interface name, and the title is interface name, dot, constructor name, then parentheses on the end. +Each interface has zero or one constructors, documented on a subpage of the interface's page. It describes the purpose of the constructor and shows what its syntax looks like, usage examples, browser compatibility information, etc. Its slug is the name of the constructor, which is exactly the same as the interface name, and the title is interface name, dot, constructor name, then parentheses on the end. Example: @@ -145,7 +145,7 @@ Examples: #### Event pages -Document events as sub pages of their target interfaces and use the slug _eventname_\_event with the title set to `Interface: eventName event`. +Document events as subpages of their target interfaces and use the slug _eventname_\_event with the title set to `Interface: eventName event`. Don't create pages for `on` event handler properties. Mention both ways to access the event on the `eventName_event` page. @@ -229,12 +229,7 @@ Now you should be ready to start writing your interface pages. Each interface re 1. **\\{{APIRef}}**: Include the \\{{APIRef}} macro in the first line of each interface page, including the name of the API as an argument, so for example \\{{APIRef("Web Audio API")}}. This macro serves to construct a reference menu on the left-hand side of the interface page, including properties and methods, and other quick links as defined in the [GroupData](https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json) macro (ask someone to add your API to an existing GroupData entry, or to create a new one, if it isn't already listed there). The menu will look something like the below screenshot. ![This screenshot shows a vertical navigation menu for the OscillatorNode interface, with multiple sublists for methods and properties, as generated by the APIRef macro ](apiref-links.png) -2. **Standardization status**: The banner indicating the standardization status should be added next (these can be placed on the same line as the \\{{APIRef}} macro.): - - - \\{{SeeCompatTable}} for an experimental feature (i.e. the spec is not at the CR level.) - - \\{{Deprecated_header}} - - \\{{Non-standard_header}} - +2. **Feature status**: A [banner indicating the feature status](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#feature_status_page_banners) (such as deprecated, non standard, or experimental) is added automatically, if needed. For that you need to [update the status in the browser-compat-data repository](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses). 3. **Description**: the first paragraph of the interface page should provide a short concise description of the interface's overarching purpose. You may also want to include a couple more paragraphs if any additional description is required. If the interface is actually a dictionary, you should use that term instead of "interface". 4. **Inheritance diagram:** Use the [`\{{InheritanceDiagram}}`](https://github.com/mdn/yari/blob/main/kumascript/macros/InheritanceDiagram.ejs) macro to embed an SVG inheritance diagram for the interface. 5. **List of properties, List of methods**: These sections should be titled "Properties" and "Methods", and provide links (using the \\{{domxref}} macro) to a reference page for each property/method of that interface, along with a description of what each one does. These should be marked up using [description/definition lists](/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN#definition_lists). Each description should be short and concise — one sentence if possible. See the "Referencing other API features with the \\{{domxref}} macro" section for a quicker way to create links to other pages. @@ -277,13 +272,9 @@ Property pages must have the following sections: 1. **Title**: the title of the page must be **InterfaceName.propertyName**. The interface name must start with a capital letter. Although an interface is implemented in JavaScript on the prototype of objects, we don't include `.prototype.` in the title, like we do in the [JavaScript reference](/en-US/docs/Web/JavaScript/Reference). 2. **\\{{APIRef}}**: Include the \\{{APIRef}} macro in the first line of each property page, including the name of the API as an argument, so for example \\{{APIRef("Web Audio API")}}. This macro serves to construct a reference menu on the left-hand side of the interface page, including properties and methods, and other quick links as defined in the [GroupData](https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json) macro (ask someone to add your API to an existing GroupData entry, or to create a new one, if it isn't already listed there). The menu will look something like the below screenshot. ![This screenshot shows a vertical navigation menu for the OscillatorNode interface, with multiple sublists for methods and properties, as generated by the APIRef macro ](apiref-links.png) -3. **Standardization status**: The banner indicating the standardization status should be added next to the interface name (these can be placed on the same line as the \\{{APIRef}} macro): +3. **Feature status**: A [banner indicating the feature status](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#feature_status_page_banners) (such as deprecated, non standard, or experimental) is added automatically, if needed. For that you need to [update the status in the browser-compat-data repository](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses). - - \\{{SeeCompatTable}} for an experimental feature (i.e. the spec is not at the CR level.) - - \\{{Deprecated_header}} - - \\{{Non-standard_header}} - -4. **Description**: the first paragraph of the property page should provide a short, concise description of the property's overarching purpose. You may also want to include a couple more paragraphs if any additional description is required. Obvious extra information to include is its default/initial value, and whether it's read only or not. The structure of the first sentence must be: +4. **Description**: the first paragraph of the property page should provide a short, concise description of the property's overarching purpose. You may also want to include a couple more paragraphs if any additional description is required. Obvious extra information to include is its default/initial value, and whether it's read-only or not. The structure of the first sentence must be: - For read-only properties - : The **`InterfaceName.property`** read-only property returns a \\{{domxref("type")}} that… @@ -315,11 +306,7 @@ Method pages need the following sections: 1. **Title**: the title of the page must be **InterfaceName.method()** (with the two terminal parentheses), but the slug (the end of the page URL) must not include the parentheses. Also the interface name must start with a capital. Although an interface is implemented in JavaScript on the prototype of objects, we don't put `.prototype.` in the title, like we do in the [JavaScript reference](/en-US/docs/Web/JavaScript/Reference). 2. **\\{{APIRef}}**: Include the \\{{APIRef}} macro in the first line of each method page, including the name of the API as an argument, so for example \\{{APIRef("Web Audio API")}}. This macro serves to construct a reference menu on the left-hand side of the interface page, including properties and methods, and other quick links as defined in the [GroupData](https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json) macro (ask someone to add your API to an existing GroupData entry, or to create a new one, if it isn't already listed there). The menu will look something like the below screenshot. ![This screenshot shows a vertical navigation menu for the OscillatorNode interface, with multiple sublists for methods and properties, as generated by the APIRef macro ](apiref-links.png) -3. **Standardization status**: Next, the banner indicating the standardization status should be added (these can be placed on the same line as the \\{{APIRef}} macro): - - - \\{{SeeCompatTable}} for an experimental feature (i.e. the spec is not at the CR level.) - - \\{{Deprecated_header}} - - \\{{Non-standard_header}} +3. **Feature status**: A [banner indicating the feature status](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#feature_status_page_banners) (such as deprecated, non standard, or experimental) is added automatically, if needed. For that you need to [update the status in the browser-compat-data repository](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses). 4. **Description**: The first paragraph of the method page should provide a short concise description of the method's overarching purpose. You may also want to include a couple more paragraphs if any additional description is required. Obvious extra information to include is its default parameter values, any theory that the method relies on, and what the parameter values do. diff --git a/files/en-us/mdn/writing_guidelines/page_structures/banners_and_notices/index.md b/files/en-us/mdn/writing_guidelines/page_structures/banners_and_notices/index.md index 8ffb8f2e8c992d0..ed85d31c7d9f9a8 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/banners_and_notices/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/banners_and_notices/index.md @@ -6,50 +6,57 @@ page-type: mdn-writing-guide {{MDNSidebar}} -Banners are added to some pages, in particular API reference, in order to highlight important factors that will affect how the described content is used. -For example, banners are used to highlight when a particular interface, method or property is deprecated, and should not be used in production code. +Banners and notices are displayed in some pages, in particular API reference, in order to highlight important factors that will affect how the described content is used. +For example, banners are used to highlight when a particular interface, method or property is deprecated, and should not be used in production code, or can only be used in a secure context. -This article describes the more important banners, and how they are added. +Banners are rendered using macros in the page content. +Some banner macros are added automatically to the page, while others are added manually. -## How to add a banner +This article describes the more important banners and how they are added. -Banners are added using macros. -Banners macros should be inserted below the page metadata, alongside the page sidebar macro. -For example, the `\{{SeeCompatTable}}` macro is added below to indicate that the [Ink API](/en-US/docs/Web/API/Ink_API) is [Experimental](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental). +## Where are banner macros added + +Banners are added using macros that are usually inserted below the page metadata, alongside the page sidebar macro. For example, in the block below, the `\{{SecureContext_Header}}` macro has been used to indicate that the {{domxref("AudioDecoder")}} interface is only available in a [secure context](/en-US/docs/Web/Security/Secure_Contexts), and `\{{SeeCompatTable}}` has been added to indicate that the interface is experimental. ```md --- -title: Ink API -slug: Web/API/Ink_API -page-type: web-api-overview +title: AudioDecoder +slug: Web/API/AudioDecoder +page-type: web-api-interface status: - experimental -browser-compat: api.Ink +browser-compat: api.AudioDecoder --- -\{{DefaultAPISidebar("Ink API")}}\{{SeeCompatTable}} +\{{APIRef("WebCodecs API")}}\{{SeeCompatTable}}\{{SecureContext_Header}} ``` -A page that has a banner will usually also have "complementary" page metadata. -For example, a page that has `\{{SeeCompatTable}}` should usually have the `experimental` status added too (as shown above) to ensure that it has appropriate icons in the sidebar. +While most banners are inserted immediately below the page metadata, the `\{{AvailableInWorkers}}` macro is added at the bottom of the first section of text, before the first heading. + +## Banners that must be added manually -> **Note:** Banner macros do not _depend_ on the metadata, but some other macro-inserted content does. -> For example, the `\{{Compat}}` macro depends on the `browser-compat` metadata value. +You need to add the following macros manually: + +- `\{{SecureContext_Header}}` — this generates a **Secure context** banner that indicates the technology is only available in a [secure context](/en-US/docs/Web/Security/Secure_Contexts). +- `\{{AvailableInWorkers}}` — this generates a note that indicates that the technology is available [web workers](/en-US/docs/Web/API/Web_Workers_API). -## What banners can/should be added +## Banners that are added automatically -The [Page type templates](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types#templates) include the most important macros. -In summary: +The following macros are automatically added to the content in order to match the statuses stored in the browser-compat-data repository: - `\{{SeeCompatTable}}` — generates a **This is an experimental technology** banner that indicates the technology is [experimental](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental). - Also add `status` of `experimental` to the page front-matter. - `\{{Deprecated_Header}}` — generates a **Deprecated** banner that indicates that use of the technology is [discouraged](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated). - Also add `status` of `deprecated` to the page front-matter. - `\{{Non-standard_Header}}` — generates a **Non-Standard** banner that indicates that use of the technology is not part of a formal specification, even if it is implemented in multiple browsers. - Also add `status` of `non-standard` to the page front-matter. -- `\{{SecureContext_Header}}` — this generates a **Secure context** banner that indicates the technology is only available in a [secure context](/en-US/docs/Web/Security/Secure_Contexts). -### Experimental: "Standards positions" banner +[Update the feature status in the browser-compat-data repository](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses) in order to change these values. + +> **Note:** While you can manually/update these macros in content, values that don't match the browser compatibility data will be replaced/removed. + +> **Note:** Pages that have the `\{{SeeCompatTable}}`, `\{{Deprecated_Header}}`, or `\{{Non-standard_Header}}` banners will also have the corresponding `experimental`, `deprecated` and `non-standard` status values in the page metadata. +> The metadata is automatically updated at the same time as the headers. +> The banner macros do not depend on this status metadata (but may one day be generated from it). + +## Experimental: "Standards positions" banner Occasionally, browser vendors disagree on how a feature is developing, and some may oppose it in its current form. In exceptional cases, MDN documents technologies in this state to encourage the web community to experiment with them, provide feedback, and help browser vendors reach a consensus. diff --git a/files/en-us/mdn/writing_guidelines/page_structures/compatibility_tables/index.md b/files/en-us/mdn/writing_guidelines/page_structures/compatibility_tables/index.md index 5d269f97770e534..55c8a6f319b0197 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/compatibility_tables/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/compatibility_tables/index.md @@ -8,14 +8,14 @@ browser-compat: api.AbortController {{MDNSidebar}} MDN has a standard format for tables that illustrate compatibility of shared technologies across all browsers, such as DOM, HTML, CSS, JavaScript, SVG, etc. -To make this data available in multiple projects programmatically, a Node.js package is built from the [`browser-compat-data` repository](https://github.com/mdn/browser-compat-data) and published to npm. +To make this data available in multiple projects programmatically, a Node.js package is built from the [browser-compat-data repository](https://github.com/mdn/browser-compat-data) and published to npm. To modify the data within these tables, comprehensive documentation along with the most recent details of conventions and JSON schemas used to represent the data can be found in the repository's [contributing guide](https://github.com/mdn/browser-compat-data/blob/main/docs/contributing.md) as well as the [data guidelines guide](https://github.com/mdn/browser-compat-data/blob/main/docs/data-guidelines/index.md). If you have questions or discover problems, you are welcome to [ask for help](/en-US/docs/MDN/Community/Communication_channels). ## Using BCD data in MDN pages -Once data has been included in the [`browser-compat-data`](https://github.com/mdn/browser-compat-data) repo, you can start dynamically including browser compatibility and specification tables based on that data within MDN pages. +Once data has been included in the [browser-compat-data](https://github.com/mdn/browser-compat-data) repo, you can start dynamically including browser compatibility and specification tables based on that data within MDN pages. To get started with BCD data in MDN pages, use the query string specified in the BCD source file for the relevant data you wish to include. For example: diff --git a/files/en-us/mdn/writing_guidelines/page_structures/feature_status/index.md b/files/en-us/mdn/writing_guidelines/page_structures/feature_status/index.md new file mode 100644 index 000000000000000..54fc3698f4541cc --- /dev/null +++ b/files/en-us/mdn/writing_guidelines/page_structures/feature_status/index.md @@ -0,0 +1,80 @@ +--- +title: Feature status +slug: MDN/Writing_guidelines/Page_structures/Feature_status +page-type: mdn-writing-guide +--- + +{{MDNSidebar}} + +A feature status provides developers with information about the implementation stage of the feature among browser vendors and is one of the following: + +- [`experimental`](https://github.com/mdn/browser-compat-data/blob/main/docs/data-guidelines/index.md#setting-experimental) +- [`non-standard`](https://github.com/mdn/browser-compat-data/blob/main/schemas/compat-data-schema.md#status-information) +- [`deprecated`](https://github.com/mdn/browser-compat-data/blob/main/docs/data-guidelines/index.md#setting-deprecated) + +If none of the above statuses apply, then the feature is considered a stable and standard feature. We don't explicitly add this status to content pages. +For more information on these terms, see the ["Experimental, deprecated, and obsolete"](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete) page. + +To see detailed instructions on how to choose a status for a feature, refer to the [choosing status properties](https://github.com/mdn/browser-compat-data/blob/main/docs/data-guidelines/index.md#choosing-status-properties) section in the `@mdn/browser-compat-data` (BCD) repository. + +## How to add or update feature statuses + +The feature statuses of all the features documented on MDN are defined in its accompanying [@mdn/browser-compat-data](https://github.com/mdn/browser-compat-data) (BCD) repository entry and are _automatically_ updated in the `mdn/content` repository whenever a new [version of BCD is released](https://github.com/mdn/browser-compat-data/releases). + +> **Warning:** +> Do not manually update feature statuses in the `mdn/content` repository. To update a feature's status, you need to [submit a pull request](https://github.com/mdn/browser-compat-data/blob/main/docs/contributing.md#updating-the-compat-data) in the BCD repository. After your changes are approved and merged in BCD, an [automated pull request](https://github.com/search?q=repo%3Amdn%2Fcontent+Synchronize+with+BCD&type=pullrequests) updates the statuses in the `mdn/content` repository. + +The automation uses [`browser-compat`](/en-US/docs/MDN/Writing_guidelines/Page_structures/Compatibility_tables#using_bcd_data_in_mdn_pages) key in the front-matter. The key stores BCD query required to locate the feature in the compatiblity data. If the `browser-compat` key has multiple values then the automation uses only the first value to render status macros. + +## How are feature statuses specified in content? + +The following sections document mechanisms using which feature statuses are rendered in MDN documents. As mentioned, you should consider these mechanisms read-only as their inclusion in the content is automated. + +### Feature status icons in sidebars + +To show status icons for a feature listed in sidebars, the [front-matter](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/CSS_function_page_template#sect1) `status` property is used: + +```yml +--- +title: Feature name +status: + - experimental + - non-standard + - deprecated +browser-compat: api.feature +--- +``` + +When sidebars are rendered, the code looks for the statuses in each page's front-matter. As mentioned before, these statuses are updated automatically; you do not need to change them manually. + +### Feature status page banners + +The following macros are used to render the status banners in page headers: + +- `\{{SeeCompatTable}}` + + - : For `experimental` status. It generates an **Experimental status** banner: + {{SeeCompatTable}} + +- `\{{Non-standard_Header}}` + + - : For `non-standard` status. It generates a **Non-Standard status** banner: + {{Non-standard_Header}} + +- `\{{Deprecated_Header}}` + - : For `deprecated` status. It generates a **Deprecated status** banner: + {{deprecated_header}} + +### Feature status icons in definition lists + +The following macros are used to render inline status icons next to definition list items: + +- [`\{{Experimental_Inline}}`](https://github.com/mdn/yari/blob/main/kumascript/macros/experimental_inline.ejs) icon: {{Experimental_Inline}} +- [`\{{Non-standard_Inline}}`](https://github.com/mdn/yari/blob/main/kumascript/macros/Non-standard_Inline.ejs) icon: {{Non-standard_Inline}} +- [`\{{Deprecated_Inline}}`](https://github.com/mdn/yari/blob/main/kumascript/macros/Deprecated_Inline.ejs) icon: {{Deprecated_Inline}} + +## See also + +- [Sidebar macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars) +- [Link macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Links) +- [List of macros](https://github.com/mdn/yari/tree/main/kumascript/macros) on GitHub diff --git a/files/en-us/mdn/writing_guidelines/page_structures/links/index.md b/files/en-us/mdn/writing_guidelines/page_structures/links/index.md index 55208d8afef92c3..276ee044b0eb063 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/links/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/links/index.md @@ -14,7 +14,7 @@ MDN provides macros that create a list of links: - [`\{{LandingPageListSubPages}}`](https://github.com/mdn/yari/blob/main/kumascript/macros/LandingPageListSubpages.ejs) - - : Inserts a definition list ({{HTMLelement("dl")}}) of the subpages of the current page, with each page's title as the {{HTMLelement("dt")}} term and its first paragraph as the {{HTMLelement("dd")}} term. + - : Inserts a definition list ({{HTMLElement("dl")}}) of the subpages of the current page, with each page's title as the {{HTMLElement("dt")}} term and its first paragraph as the {{HTMLElement("dd")}} term. - [`\{{ListSubpagesForSidebar()}}`](https://github.com/mdn/yari/blob/main/kumascript/macros/ListSubpagesForSidebar.ejs) @@ -26,7 +26,7 @@ MDN provides macros that create a list of links: ### Example link list -To include an ordered list of links which includes this page and its siblings. write the following: +To include an ordered list of links that includes this page and its siblings, write the following: ```md \{{ListSubpagesForSidebar("/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros", 1)}} @@ -73,4 +73,4 @@ To learn which parameters each macro supports and the order of parameters for ea - [Using macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros) - [Macros](https://github.com/mdn/yari/tree/main/kumascript/macros) on Github - [Commonly used macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros), including BCD macros ( `\{{Compat}}`, `\{{Compat(<feature>)}}`, and `\{{Compat(<feature>, <depth>)}}`) and specification macros (`\{{Specifications}}` / `\{{Specifications(<feature>)}}`) -- [Banners and notices guide](/en-US/docs/MDN/Writing_guidelines/Page_structures/Banners_and_notices)including the `\{{SeeCompatTable}}`, `\{{Deprecated_Header}}`, and `\{{SecureContext_Header}}` macros. +- [Banners and notices guide](/en-US/docs/MDN/Writing_guidelines/Page_structures/Banners_and_notices) including the `\{{SeeCompatTable}}`, `\{{Deprecated_Header}}`, and `\{{SecureContext_Header}}` macros. diff --git a/files/en-us/mdn/writing_guidelines/page_structures/macros/commonly_used_macros/index.md b/files/en-us/mdn/writing_guidelines/page_structures/macros/commonly_used_macros/index.md index bea5e4bca803399..a29ee791ced66e6 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/macros/commonly_used_macros/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/macros/commonly_used_macros/index.md @@ -16,7 +16,7 @@ See [Other macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Oth MDN provides a number of link macros for easing the creation of links to reference pages, glossary entries, and other topics. Link macros are recommended over normal Markdown links because they are succinct and translation-friendly. -For example a glossary or reference link created using a macro does not need to be translated: in other locales it will automatically link to the correct version of the file. +For example, a glossary or reference link created using a macro does not need to be translated: in other locales it will automatically link to the correct version of the file. ### Glossary links @@ -28,7 +28,7 @@ This macro accepts one required parameter and one optional parameter: ### Linking to pages in references -There are macros for locale-independent linking to pages in specific reference areas of MDN: JavaScript, CSS, HTML elements, SVG etc. +There are macros for locale-independent linking to pages in specific reference areas of MDN: JavaScript, CSS, HTML elements, SVG, etc. The macros are easy to use. Minimally all you need to do is specify the name of the item to link to in the first argument. @@ -152,7 +152,7 @@ Most macros will also take a second argument allowing you to change the display [`Previous`](https://github.com/mdn/yari/blob/main/kumascript/macros/Previous.ejs), [`Next`](https://github.com/mdn/yari/blob/main/kumascript/macros/Next.ejs), and [`PreviousNext`](https://github.com/mdn/yari/blob/main/kumascript/macros/PreviousNext.ejs) provide navigation controls for articles which are part of sequences. For the single-way templates, the only parameter needed is the wiki location of the previous or next article in the sequence. For [`PreviousNext`](https://github.com/mdn/yari/blob/main/kumascript/macros/PreviousNext.ejs), the two parameters needed are the wiki locations of the appropriate articles. -The first parameter is for the previous article and the second is for the next article. +The first parameter is for the previous article, and the second is for the next article. ## Code samples @@ -237,11 +237,12 @@ The templates should be placed directly underneath the main page title (or bread They can also be used to mark up a section on a page. - [`non-standard_header`](https://github.com/mdn/yari/blob/main/kumascript/macros/Non-standard_Header.ejs): `\{{Non-standard_Header}}` {{Non-standard_Header}} -- [`SeeCompatTable`](https://github.com/mdn/yari/blob/main/kumascript/macros/SeeCompatTable.ejs) should be used on pages that document [experimental features](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental). +- [`SeeCompatTable`](https://github.com/mdn/yari/blob/main/kumascript/macros/SeeCompatTable.ejs) used on pages + that document [experimental features](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental). Example: `\{{SeeCompatTable}}` {{SeeCompatTable}} - [`deprecated_header`](https://github.com/mdn/yari/blob/main/kumascript/macros/Deprecated_Header.ejs): `\{{Deprecated_Header}}` {{Deprecated_Header}} - [`secureContext_header`](https://github.com/mdn/yari/blob/main/kumascript/macros/secureContext_header.ejs). - Should be used on main pages like interface pages, API overview pages, and API entry points (e.g. `navigator.xyz`) but usually not on sub-pages like method and property pages. + Should be used on main pages like interface pages, API overview pages, and API entry points (e.g. `navigator.xyz`) but usually not on subpages like method and property pages. Example: `\{{SecureContext_Header}}` {{SecureContext_Header}} ### Indicating that a feature is available in web workers @@ -277,4 +278,5 @@ The following macros are included on all reference pages, but are also supported - [Sidebar macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars) - [Page templates](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types#page_templates) - [Page components](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide#page_components) -- [List of macros](https://github.com/mdn/yari/tree/main/kumascript/macros) on Github +- [Feature status macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status) +- [List of macros](https://github.com/mdn/yari/tree/main/kumascript/macros) on GitHub diff --git a/files/en-us/mdn/writing_guidelines/page_structures/macros/index.md b/files/en-us/mdn/writing_guidelines/page_structures/macros/index.md index 66ac12b8cfb9368..480f52264531267 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/macros/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/macros/index.md @@ -12,7 +12,8 @@ The [KumaScript guide](https://github.com/mdn/yari/blob/main/docs/kumascript/REA ## How macros are implemented -Macros on MDN are implemented using server-executed [JavaScript](/en-US/docs/Web/JavaScript) code, interpreted using [Node.js](https://nodejs.org/en/). On top of that we have a number of libraries we've implemented that provide services and features to let macros interact with the platform and its contents. +Macros on MDN are implemented using server-executed [JavaScript](/en-US/docs/Web/JavaScript) code, interpreted using [Node.js](https://nodejs.org/en/). +On top of that, we have a number of libraries we've implemented that provide services and features to let macros interact with the platform and its contents. ## Using a macro in content @@ -27,17 +28,18 @@ A few notes about macro calls: - Macro names are case-sensitive, but some attempt is made to correct for common capitalization errors; you may use all lowercase even if the macro name uses caps within it, and you may capitalize a macro whose name normally starts with a lower-case letter. - Parameters are separated by commas. - If there are no parameters, you may leave out the parentheses entirely; `\{{macroname()}}` and `\{{macroname}}` are identical. -- Numeric parameters can be in quotes, or not. It's up to you (however, if you have a version number with multiple decimals in it, it needs to be in quotes). +- Numeric parameters can be in quotes or not. It's up to you (however, if you have a version number with multiple decimals in it, it needs to be in quotes). - If you get errors, review your code carefully. If you still can't figure out what's going on, see [Troubleshooting KumaScript errors](https://github.com/mdn/yari/blob/main/docs/kumascript/troubleshooting-errors.md) for help. Macros are heavily cached; for any set of input values (both parameters and environmental values such as the URL for which the macro was run), the results are stored and reused. This means that the macro is only actually run when the inputs change. Macros can be as simple as just inserting a larger block of text or swapping in contents from another part of MDN, or as complex as building an entire index of content by searching through parts of the site, styling the output, and adding links. -You can read up on our most commonly-used macros on the [Commonly-used macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros) page; also, you can browse through the [complete sources for all macros](https://github.com/mdn/yari/tree/main/kumascript/macros). Most of the macro sources have documentation built into them, as comments at the top. +You can read up on our most commonly used macros on the [Commonly used macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros) page; also, you can browse through the [complete sources for all macros](https://github.com/mdn/yari/tree/main/kumascript/macros). Most of the macro sources have documentation built into them, as comments at the top. ## See also - [Sidebar macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars) - [Link macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Links) -- [List of macros](https://github.com/mdn/yari/tree/main/kumascript/macros) on Github +- [Feature status macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status) +- [List of macros](https://github.com/mdn/yari/tree/main/kumascript/macros) on GitHub diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_constructor_subpage_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_constructor_subpage_template/index.md index 69931d3e612784a..2ab2b9e656a2ae6 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_constructor_subpage_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_constructor_subpage_template/index.md @@ -30,7 +30,7 @@ browser-compat: path.to.feature.NameOfTheConstructor > ``` > > - **title** -> - : Title heading displayed at top of page. +> - : Title heading displayed at the top of the page. > Format as _NameOfTheParentInterface_**()**. > For example, the [Request()](/en-US/docs/Web/API/Request/Request) constructor has a _title_ of `Request()`. > - **slug** @@ -40,7 +40,7 @@ browser-compat: path.to.feature.NameOfTheConstructor > - **page-type** > - : The `page-type` key for Web/API constructors is always `web-api-constructor`. > - **status** -> - : Include (appropriate) technology status keys: [**experimental**](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental), [**deprecated**](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated), **non-standard** (if not on a standards track). +> - : Flags describing the status of this feature. An array which may contain one or more of the following: `experimental`, `deprecated`, `non-standard`. This key should not be set manually: it is set automatically based on values in the browser compatibility data for the feature. See ["How to add or update feature statuses"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses). > - **browser-compat** > > - : Replace the placeholder value `path.to.feature.NameOfTheConstructor` with the query string for the constructor in the [Browser compat data repo](https://github.com/mdn/browser-compat-data). @@ -54,13 +54,15 @@ 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 front matter). -> You should update or delete them according to the advice below: +> These macros are automatically added by the toolchain (there is no need to add/remove): > > - `\{{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). -> If the technology you are documenting is not experimental, you should remove this. > If it is experimental, and the technology is hidden behind a pref in Firefox, you should also fill in an entry for it in the [Experimental features in Firefox](/en-US/docs/Mozilla/Firefox/Experimental_features) page. > - `\{{Deprecated_Header}}` — this generates a **Deprecated** banner that indicates that use of the technology is [discouraged](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated). -> If it isn't, then you can remove the macro call. +> - `\{{Non-standard_Header}}` — this generates a **Non-standard** banner that indicates that the feature is not part of any specification. +> +> You should update or delete the following macros according to the advice below: +> > - `\{{SecureContext_Header}}` — this generates a **Secure context** banner that indicates the technology is only available in a [secure context](/en-US/docs/Web/Security/Secure_Contexts). > If it isn't, then you can remove the macro call. > If it is, then you should also fill in an entry for it in the [Features restricted to secure contexts](/en-US/docs/Web/Security/Secure_Contexts/features_restricted_to_secure_contexts) page. @@ -69,11 +71,13 @@ browser-compat: path.to.feature.NameOfTheConstructor > 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. > -> Samples of the **Experimental**, **Secure context**, and **Deprecated** banners are shown right after this note block. +> Do not provide status header macros manually. Refer to the section [How to add or update feature statuses](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses) to add these statuses to the page. +> +> Samples of the **Secure context**, **Experimental**, **Deprecated**, and **Non-standard** banners are shown right after this note block. > > _Remember to remove this whole explanatory note before publishing._ -{{SeeCompatTable}}{{SecureContext_Header}}{{Deprecated_Header}} +{{SecureContext_Header}}{{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}} 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. @@ -93,7 +97,7 @@ 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. +Include a description of the constructor's return value, including the data type and what it represents. This is normally just "An instance of the `\{{domxref("NameOfTheParentInterface")}}` object." _To use this macro, remove the backticks and backslash in the markdown file._ diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_event_subpage_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_event_subpage_template/index.md index df506013a8d90cb..2aaf26a0fa22785 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_event_subpage_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_event_subpage_template/index.md @@ -30,7 +30,7 @@ browser-compat: path.to.feature.NameOfTheEvent_event > ``` > > - **title** -> - : Title heading displayed at top of page. +> - : Title heading displayed at the top of the page. > Format as "_NameOfTheParentInterface_**:** _NameOfTheEvent_ **event**". > For example, the [animationcancel](/en-US/docs/Web/API/Element/animationcancel_event) event of the [Window](/en-US/docs/Web/API/Window) interface has a _title_ of `Window: animationcancel event`. > - **slug** @@ -39,7 +39,7 @@ browser-compat: path.to.feature.NameOfTheEvent_event > - **page-type** > - : The `page-type` key for Web/API events is always `web-api-event`. > - **status** -> - : Include (appropriate) technology status keys: [**experimental**](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental), [**deprecated**](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated), **non-standard** (if not on a standards track). +> - : Flags describing the status of this feature. An array which may contain one or more of the following: `experimental`, `deprecated`, `non-standard`. This key should not be set manually: it is set automatically based on values in the browser compatibility data for the feature. See [How to add or update feature statuses](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses). > - **browser-compat** > > - : Replace the placeholder value `path.to.feature.NameOfTheEvent_event` with the query string for the event in the [Browser compat data repo](https://github.com/mdn/browser-compat-data). @@ -53,13 +53,15 @@ browser-compat: path.to.feature.NameOfTheEvent_event > **Top-of-page macros** > > A number of macro calls appear at the top of the content section (immediately below the page frontmatter). -> You should update or delete them according to the advice below: +> These macros are automatically added by the toolchain (there is no need to add/remove): > > - `\{{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). -> If the technology you are documenting is not experimental, you should remove this. > If it is experimental, and the technology is hidden behind a pref in Firefox, you should also fill in an entry for it in the [Experimental features in Firefox](/en-US/docs/Mozilla/Firefox/Experimental_features) page. > - `\{{Deprecated_Header}}` — this generates a **Deprecated** banner that indicates that use of the technology is [discouraged](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated). -> If it isn't, then you can remove the macro call. +> - `\{{Non-standard_Header}}` — this generates a **Non-standard** banner that indicates that the feature is not part of any specification. +> +> You should update or delete the following macros according to the advice below: +> > - `\{{SecureContext_Header}}` — this generates a **Secure context** banner that indicates the technology is only available in a [secure context](/en-US/docs/Web/Security/Secure_Contexts). > If it isn't, then you can remove the macro call. > If it is, then you should also fill in an entry for it in the [Features restricted to secure contexts](/en-US/docs/Web/Security/Secure_Contexts/features_restricted_to_secure_contexts) page. @@ -68,21 +70,23 @@ browser-compat: path.to.feature.NameOfTheEvent_event > 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. > -> Samples of the **Experimental**, **Secure context**, and **Deprecated** banners are shown right after this note block. +> Do not provide status header macros manually. Refer to the section ["How to add or update feature statuses"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses) to add these statuses to the page. +> +> Samples of the **Secure context**, **Experimental**, **Deprecated**, and **Non-standard** banners are shown right after this note block. > > --- > > **Parent object link** > > Add a link to this new page from its parent object's _Events_ section. -> For example [Element: wheel event](/en-US/docs/Web/API/Element/wheel_event) is linked from [`Element` Events](/en-US/docs/Web/API/Element#events). +> For example, [Element: wheel event](/en-US/docs/Web/API/Element/wheel_event) is linked from [`Element` Events](/en-US/docs/Web/API/Element#events). > > 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). +> If this is a new "class" of event, then you should add a 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._ -{{SeeCompatTable}}{{SecureContext_Header}}{{Deprecated_Header}} +{{SecureContext_Header}}{{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}} 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. diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_landing_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_landing_page_template/index.md index be9dd98916fbbd2..dc9d625cd3b4db7 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_landing_page_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_landing_page_template/index.md @@ -28,7 +28,7 @@ page-type: mdn-writing-guide > ``` > > - **title** -> - : Title heading displayed at top of page. +> - : Title heading displayed at the top of the page. > This is the name of the API followed by the text "API": _NameOfTheAPI_ **API**. > For example, [WebXR Device](/en-US/docs/Web/API/WebXR_Device_API) has a title of _WebXR Device API_, [Fetch](/en-US/docs/Web/API/Fetch_API) has a title of _Fetch API_. > - **slug** @@ -38,20 +38,22 @@ page-type: mdn-writing-guide > - **page-type** > - : The `page-type` key for Web/API landing pages is always `web-api-overview`. > - **status** -> - : Include (appropriate) technology status keys: [**experimental**](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental), [**deprecated**](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated), **non-standard** (if not on a standards track). +> - : Flags describing the status of this feature. An array which may contain one or more of the following: `experimental`, `deprecated`, `non-standard`. This key should not be set manually: it is set automatically based on values in the browser compatibility data for the feature. See ["How to add or update feature statuses"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses). > > --- > > **Top-of-page macros** > > 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: +> These macros are automatically added by the toolchain (there is no need to add/remove): > > - `\{{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). -> If the technology you are documenting is not experimental, you should remove this. > If it is experimental, and the technology is hidden behind a pref in Firefox, you should also fill in an entry for it in the [Experimental features in Firefox](/en-US/docs/Mozilla/Firefox/Experimental_features) page. > - `\{{Deprecated_Header}}` — this generates a **Deprecated** banner that indicates that use of the technology is [discouraged](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated). -> If it isn't, then you can remove the macro call. +> - `\{{Non-standard_Header}}` — this generates a **Non-standard** banner that indicates that the feature is not part of any specification. +> +> You should update or delete the following macros according to the advice below: +> > - `\{{SecureContext_Header}}` — this generates a **Secure context** banner that indicates the technology is only available in a [secure context](/en-US/docs/Web/Security/Secure_Contexts). > If it isn't, then you can remove the macro call. > If it is, then you should also fill in an entry for it in the [Features restricted to secure contexts](/en-US/docs/Web/Security/Secure_Contexts/features_restricted_to_secure_contexts) page. @@ -61,11 +63,15 @@ page-type: mdn-writing-guide > 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. > +> Do not provide status header macros manually. Refer to the section ["How to add or update feature statuses"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses) to add these statuses to the page. +> +> Samples of the **Secure context**, **Experimental**, **Deprecated**, and **Non-standard** banners are shown right after this note block. +> > --- > > **Browser compatibility** > -> API landing pages optionally have a browser compatibility section that shows compatibility tables for one or more of the most important interfaces in the API. If the compatibility is similar for most interfaces in the API then often just one compatibility table is needed. If compatibility across the API is complicated/impossible to capture in a few tables, this sections should be omitted. +> API landing pages optionally have a browser compatibility section that shows compatibility tables for one or more of the most important interfaces in the API. If the compatibility is similar for most interfaces in the API, then often just one compatibility table is needed. If compatibility across the API is complicated/impossible to capture in a few tables, this sections should be omitted. > > To fill in the browser compatibility section, you may first need to create/update entries for the API interfaces in our [Browser compat data repo](https://github.com/mdn/browser-compat-data) — see our [guide on how to do this](/en-US/docs/MDN/Writing_guidelines/Page_structures/Compatibility_tables). > @@ -85,14 +91,14 @@ page-type: mdn-writing-guide > > _Remember to remove this whole explanatory note before publishing_ -{{securecontext_header}} +{{SecureContext_Header}}{{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}} 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 In this section, describe the API's purpose and usage cases in a bit more detail — why was a need recognized for it? -What problems does it solve? What concepts does it involve? How do you use it, from a high level perspective? +What problems does it solve? What concepts does it involve? How do you use it, from a high-level perspective? Don't go into a lot of detail in this section, and don't include code examples. If there are a lot of concepts to explain around this API, you should explain them in a separate "Fundamentals" or "Concepts" article (e.g. [Fundamentals of WebXR](/en-US/docs/Web/API/WebXR_Device_API/Fundamentals)). diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_method_subpage_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_method_subpage_template/index.md index 58ea17a6cb7e47e..7ac07d345a0832b 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_method_subpage_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_method_subpage_template/index.md @@ -30,7 +30,7 @@ browser-compat: path.to.feature.NameOfTheMethod > ``` > > - **title** -> - : Title heading displayed at top of page. +> - : Title heading displayed at the top of the page. > Format as _NameOfTheParentInterface_**.**_NameOfTheMethod_**()**. > For example, the [count()](/en-US/docs/Web/API/IDBIndex/count) method of the [IDBIndex](/en-US/docs/Web/API/IDBIndex) interface has a _title_ of `IDBIndex.count()`. > - **slug** @@ -45,7 +45,7 @@ browser-compat: path.to.feature.NameOfTheMethod > - **page-type** > - : The `page-type` key for Web/API methods is either `web-api-instance-method` (for instance methods) or `web-api-static-method` (for static methods). > - **status** -> - : Include (appropriate) technology status keys: [**experimental**](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental), [**deprecated**](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated), **non-standard** (if not on a standards track). +> - : Flags describing the status of this feature. An array which may contain one or more of the following: `experimental`, `deprecated`, `non-standard`. This key should not be set manually: it is set automatically based on values in the browser compatibility data for the feature. See ["How to add or update feature statuses"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses). > - **browser-compat** > > - : Replace the placeholder value `path.to.feature.NameOfTheMethod` with the query string for the method in the [Browser compat data repo](https://github.com/mdn/browser-compat-data). @@ -59,13 +59,15 @@ 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 front matter). -> You should update or delete them according to the advice below: +> These macros are automatically added by the toolchain (there is no need to add/remove): > > - `\{{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). -> If the technology you are documenting is not experimental, you should remove this. > If it is experimental, and the technology is hidden behind a pref in Firefox, you should also fill in an entry for it in the [Experimental features in Firefox](/en-US/docs/Mozilla/Firefox/Experimental_features) page. > - `\{{Deprecated_Header}}` — this generates a **Deprecated** banner that indicates that use of the technology is [discouraged](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated). -> If it isn't, then you can remove the macro call. +> - `\{{Non-standard_Header}}` — this generates a **Non-standard** banner that indicates that the feature is not part of any specification. +> +> You should update or delete the following macros according to the advice below: +> > - `\{{SecureContext_Header}}` — this generates a **Secure context** banner that indicates the technology is only available in a [secure context](/en-US/docs/Web/Security/Secure_Contexts). > If it isn't, then you can remove the macro call. > If it is, then you should also fill in an entry for it in the [Features restricted to secure contexts](/en-US/docs/Web/Security/Secure_Contexts/features_restricted_to_secure_contexts) page. @@ -74,11 +76,13 @@ browser-compat: path.to.feature.NameOfTheMethod > 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. > -> Samples of the **Experimental**, **Secure context**, and **Deprecated** banners are shown right after this note block. +> Do not provide status header macros manually. Refer to the section ["How to add or update feature statuses"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses) to add these statuses to the page. +> +> Samples of the **Secure context**, **Experimental**, **Deprecated**, and **Non-standard** banners are shown right after this note block. > > _Remember to remove this whole explanatory note before publishing._ -{{SeeCompatTable}}{{SecureContext_header}}{{Deprecated_Header}} +{{SecureContext_Header}}{{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}} 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. @@ -94,7 +98,7 @@ Fill in a syntax box, according to the guidance in our [syntax sections](/en-US/ - `parameter2` - : etc. -> **Note:** This section is mandatory. If there aren't any parameter, put "None." instead of the definition list. +> **Note:** This section is mandatory. If there aren't any parameters, put `None.` instead of the definition list. ### Return value diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_property_subpage_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_property_subpage_template/index.md index efb3f6c0de98154..b2fa28681aeff9a 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_property_subpage_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_property_subpage_template/index.md @@ -30,7 +30,7 @@ browser-compat: path.to.feature.NameOfTheProperty > ``` > > - **title** -> - : Title heading displayed at top of page. +> - : Title heading displayed at the top of the page. > Format as _NameOfTheParentInterface_**.**_NameOfTheProperty_. > For example, the [`capabilities`](/en-US/docs/Web/API/VRDisplay/capabilities) property of the [`VRDisplay`](/en-US/docs/Web/API/VRDisplay) interface has a `title` of `VRDisplay.capabilities`. > - **slug** @@ -43,7 +43,7 @@ browser-compat: path.to.feature.NameOfTheProperty > - **page-type** > - : The `page-type` key for Web/API properties is either `web-api-instance-property` (for instance properties) or `web-api-static-property` (for static properties). > - **status** -> - : Include (appropriate) technology status keys: [**experimental**](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental), [**deprecated**](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated), **non-standard** (if not on a standards track). +> - : Flags describing the status of this feature. An array which may contain one or more of the following: `experimental`, `deprecated`, `non-standard`. This key should not be set manually: it is set automatically based on values in the browser compatibility data for the feature. See ["How to add or update feature statuses"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses). > - **browser-compat** > > - : Replace the placeholder value `path.to.feature.NameOfTheProperty` with the query string for the property in the [Browser compat data repo](https://github.com/mdn/browser-compat-data). @@ -57,13 +57,15 @@ browser-compat: path.to.feature.NameOfTheProperty > **Top-of-page macros** > > 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: +> These macros are automatically added by the toolchain (there is no need to add/remove): > > - `\{{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). -> If the technology you are documenting is not experimental, you should remove this. > If it is experimental, and the technology is hidden behind a pref in Firefox, you should also fill in an entry for it in the [Experimental features in Firefox](/en-US/docs/Mozilla/Firefox/Experimental_features) page. > - `\{{Deprecated_Header}}` — this generates a **Deprecated** banner that indicates that use of the technology is [discouraged](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated). -> If it isn't, then you can remove the macro call. +> - `\{{Non-standard_Header}}` — this generates a **Non-standard** banner that indicates that the feature is not part of any specification. +> +> You should update or delete the following macros according to the advice below: +> > - `\{{SecureContext_Header}}` — this generates a **Secure context** banner that indicates the technology is only available in a [secure context](/en-US/docs/Web/Security/Secure_Contexts). > If it isn't, then you can remove the macro call. > If it is, then you should also fill in an entry for it in the [Features restricted to secure contexts](/en-US/docs/Web/Security/Secure_Contexts/features_restricted_to_secure_contexts) page. @@ -72,11 +74,13 @@ browser-compat: path.to.feature.NameOfTheProperty > 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. > -> Samples of the **Experimental**, **Secure context**, and **Deprecated** banners are shown right after this note block. +> Do not provide status header macros manually. Refer to the section ["How to add or update feature statuses"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses) to add these statuses to the page. +> +> Samples of the **Secure context**, **Experimental**, **Deprecated**, and **Non-standard** banners are shown right after this note block. > > _Remember to remove this whole explanatory note before publishing._ -{{SeeCompatTable}}{{SecureContext_Header}}{{Deprecated_Header}} +{{SecureContext_Header}}{{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}} Begin the content on the page with an introductory paragraph — start by naming the property, saying what interface it is part of, and saying what it does. This should ideally be one or two short sentences. diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_reference_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_reference_page_template/index.md index e7395aa26a801d3..a061895460a90a6 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_reference_page_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_reference_page_template/index.md @@ -30,13 +30,13 @@ browser-compat: path.to.feature.NameOfTheInterface > ``` > > - **title** -> - : Title heading displayed at top of page. This is just the name of the interface. For example, the [Request](/en-US/docs/Web/API/Request) interface page has a _title_ of _Request_. +> - : Title heading displayed at the top of the page. This is just the name of the interface. For example, the [Request](/en-US/docs/Web/API/Request) interface page has a _title_ of _Request_. > - **slug** > - : The end of the URL path after `https://developer.mozilla.org/en-US/docs/`). This will be formatted like `Web/API/NameOfTheParentInterface`. For example, [Request](/en-US/docs/Web/API/Request) slug is "Web/API/Request". > - **page-type** > - : The `page-type` key for Web/API interfaces is always `web-api-interface`. > - **status** -> - : Include (appropriate) technology status keys: [**experimental**](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental), [**deprecated**](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated), **non-standard** (if not on a standards track). +> - : Flags describing the status of this feature. An array which may contain one or more of the following: `experimental`, `deprecated`, `non-standard`. This key should not be set manually: it is set automatically based on values in the browser compatibility data for the feature. See ["How to add or update feature statuses"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses). > - **browser-compat** > > - : Replace the placeholder value `path.to.feature.NameOfTheMethod` with the query string for the method in the [Browser compat data repo](https://github.com/mdn/browser-compat-data). The toolchain automatically uses the key to populate the compatibility and specification sections (replacing the `\{{Compat}}` and `\{{Specifications}}` macros). @@ -52,18 +52,21 @@ browser-compat: path.to.feature.NameOfTheInterface > By default, there are five macro calls at the top of a template. You should update or delete them according to the advice below. > > - `\{{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 KumaScript 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. -> - `\{{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). If the technology you are documenting is not experimental, you can remove this. If it is experimental, and the technology is hidden behind a pref in Firefox, you should also fill in an entry for it in the [Experimental features in Firefox](/en-US/docs/Mozilla/Firefox/Experimental_features) page. +> - `\{{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). If it is experimental, and the technology is hidden behind a pref in Firefox, you should also fill in an entry for it in the [Experimental features in Firefox](/en-US/docs/Mozilla/Firefox/Experimental_features) page. +> - `\{{Deprecated_Header}}` — this generates a **Deprecated** banner that indicates the technology is [deprecated](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated). +> - `\{{Non-standard_Header}}` — this generates a **Non-standard** banner that indicates that the feature is not part of any specification. > - `\{{SecureContext_Header}}` — this generates a **Secure context** banner that indicates the technology is only available in a [secure context](/en-US/docs/Web/Security/Secure_Contexts). If it isn't, then you can remove the macro call. If it is, then you should also fill in an entry for it in the [Features restricted to secure contexts](/en-US/docs/Web/Security/Secure_Contexts/features_restricted_to_secure_contexts) page. -> - `\{{Deprecated_Header}}` — this generates a **Deprecated** banner that indicates the technology is [deprecated](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated). If it isn't, then you can remove the macro call. > - `\{{Interface_Overview("GroupDataName")}} {{Experimental_Inline}}` — this generates the main body of the page (Constructor, Properties, Methods and Events). > -> Samples of the **Experimental**, **Secure context**, and **Deprecated** banners are shown right after this note block. +> Do not provide status header macros manually. Refer to the section ["How to add or update feature statuses"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses) to add these statuses to the page. +> +> Samples of the **Secure context**, **Experimental**, **Deprecated**, and **Non-standard** banners are shown right after this note block. > > _Remember to remove this whole explanatory note before publishing._ -{{SeeCompatTable}}{{SecureContext_Header}}{{Deprecated_Header}} +{{SecureContext_Header}}{{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}} -The summary paragraph — start by naming the interface, saying what API 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 Interface's summary on the corresponding API landing page. +The summary paragraph — start by naming the interface, saying what API 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 Interface's summary on the corresponding API landing page. {{InheritanceDiagram}} diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/aria_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/aria_page_template/index.md index 5cbe4142cfa9fe2..69b1e51805f42ba 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/aria_page_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/aria_page_template/index.md @@ -16,12 +16,12 @@ An ARIA role page should have a `title` and `slug` of `ARIA: Name Of The Role`. A number of macro calls appear at the top of the content section. You should update or delete them according to the advice below: -- \\{{deprecated_header}}—generates a **Deprecated** banner that indicates the technology is [deprecated](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated). If it isn't, then you can remove the macro call. - \\{{ariaref}}—generates a suitable ARIA sidebar, depending on what tags are included on the page. -### Tags +### Statuses -In ARIA role or attribute subpages, you need to include the following tags (see the _Tags_ section at the bottom of the editor UI): **ARIA**, **Reference**, **ARIA Role** or **ARIA Attribute**, _the name of the Role or Attribute_ (e.g. **ARIA button** or **aria-labelledby**), **ARIA widget,** **Experimental** (if the role or attribute is [experimental](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental)), and **Deprecated** (if it is [deprecated](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated)). +Do not add or edit status keys manually. +To include the (appropriate) feature status key — [**experimental**](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental), [**deprecated**](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated), or **non-standard** — see the section ["How to add or update feature statuses"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses). ### Specifications @@ -37,7 +37,7 @@ Additional resources: ## Page template -The summary paragraph—start by naming the role or attribute and saying what it does. This should ideally be 1 or 2 short sentences. This content appears as a tool tip on links to this page, so craft it well. +The summary paragraph—start by naming the role or attribute and saying what it does. This should ideally be one or two short sentences. This content appears as a tool tip on links to this page, so craft it well. ```html diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_function_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_function_page_template/index.md index 555b301e83b0613..08117b741b3eed7 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_function_page_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_function_page_template/index.md @@ -38,7 +38,7 @@ browser-compat: css.functions.NameOfTheFunction > - **page-type** > - : The `page-type` value for CSS functions is `css-function`. > - **status** -> - : If applicable, the value of the technology `status` key can be [**experimental**](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental), [**deprecated**](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated), and/or **non-standard** (if not on a standards track). +> - : Flags describing the status of this feature. An array which may contain one or more of the following: `experimental`, `deprecated`, `non-standard`. This key should not be set manually: it is set automatically based on values in the browser compatibility data for the feature. See ["How to add or update feature statuses"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses). > - **browser-compat** > - : Replace the placeholder value css.types.NameOfTheFunction with the query string for the function in the [Browser compat data repo](https://github.com/mdn/browser-compat-data/tree/main/css/types). Check the _Other macros in the page_ section of this note block to see how this key-value is used to generate content for the _Specifications_ and _Browser compatibility_ sections. > @@ -47,17 +47,21 @@ browser-compat: css.functions.NameOfTheFunction > **Top-of-the-page macros** > > 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: +> These macros are automatically added by the toolchain (there is no need to add/remove): > > - `\{{SeeCompatTable}}`: This macro generates an **Experimental** banner, which indicates that the technology is [experimental](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental). -> If the technology you are documenting is not experimental, you can remove this macro. > If the technology is experimental and is hidden behind a preference in Firefox, you should also fill in an entry for it in the [Experimental features in Firefox](/en-US/docs/Mozilla/Firefox/Experimental_features) page. > - `\{{Deprecated_Header}}`: This macro generates a **Deprecated** banner, which indicates that the use of the technology is [discouraged](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated). -> If it isn't, then you can remove the macro call. +> - `\{{Non-standard_Header}}` — this generates a **Non-standard** banner that indicates that the feature is not part of any specification. +> +> You should update or delete the following macros according to the advice below: +> > - `\{{CSSRef}}`: This macro must be present on every CSS page. It generates a suitable CSS sidebar, depending on the tags included on the page. > Remember to remove the `\{{MDNSidebar}}` macro when you use this template. > -> Samples of the **Experimental** and **Deprecated** banners are shown right after this note block. +> Do not provide status header macros manually. Refer to the section ["How to add or update feature statuses"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses) to add these statuses to the page. +> +> Samples of the **Experimental**, **Deprecated**, and **Non-standard** banners are shown right after this note block. > > --- > @@ -71,7 +75,7 @@ browser-compat: css.functions.NameOfTheFunction > > _Remember to remove this note block before publishing._ -{{SeeCompatTable}}{{deprecated_header}}{{CSSRef}} +{{CSSRef}}{{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}} Begin the content on the page with an introductory paragraph, which names the function and says what it does. This should ideally be one or two short sentences. diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_property_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_property_page_template/index.md index cd356d6f18edbde..6e41506527b57d9 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_property_page_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_property_page_template/index.md @@ -38,7 +38,7 @@ browser-compat: css.properties.NameOfTheProperty > - **page-type** > - : The `page-type` value for CSS properties is `css-property`. For a shorthand CSS property, the value is `css-shorthand-property`. For example, the `page-type` value for the [animation](/en-US/docs/Web/CSS/animation) property is `css-shorthand-property` because it is a shorthand property, whereas the `page-type` value for the [animation-delay](/en-US/docs/Web/CSS/animation-delay) property is `css-property`. > - **status** -> - : If applicable, the value of the technology `status` key can be [**experimental**](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental), [**deprecated**](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated), and/or **non-standard** (if not on a standards track). +> - : Flags describing the status of this feature. An array which may contain one or more of the following: `experimental`, `deprecated`, `non-standard`. This key should not be set manually: it is set automatically based on values in the browser compatibility data for the feature. See ["How to add or update feature statuses"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses). > - **browser-compat** > - : Replace the placeholder value css.properties.NameOfTheProperty with the query string for the property in the [Browser compat data repo](https://github.com/mdn/browser-compat-data/tree/main/css/properties). Check the _Other macros in the page_ section of this note block to see how this key-value is used to generate content for the _Specifications_ and _Browser compatibility_ sections. > @@ -47,17 +47,21 @@ browser-compat: css.properties.NameOfTheProperty > **Top-of-the-page macros** > > 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: +> These macros are automatically added by the toolchain (there is no need to add/remove): > > - `\{{SeeCompatTable}}`: This macro generates an **Experimental** banner, which indicates that the technology is [experimental](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental). -> If the technology you are documenting is not experimental, you can remove this macro. > If the technology is experimental and is hidden behind a preference in Firefox, you should also fill in an entry for it in the [Experimental features in Firefox](/en-US/docs/Mozilla/Firefox/Experimental_features) page. > - `\{{Deprecated_Header}}`: This macro generates a **Deprecated** banner, which indicates that the use of the technology is [discouraged](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated). -> If it isn't, then you can remove the macro call. +> - `\{{Non-standard_Header}}` — this generates a **Non-standard** banner that indicates that the feature is not part of any specification. +> +> You should update or delete the following macros according to the advice below: +> > - `\{{CSSRef}}`: This macro must be present on every CSS property page. It generates a suitable CSS sidebar, depending on the tags included on the page. > Remember to remove the `\{{MDNSidebar}}` macro when you use this template. > -> Samples of the **Experimental** and **Deprecated** banners are shown right after this note block. +> Do not provide status header macros manually. Refer to the section ["How to add or update feature statuses"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses) to add these statuses to the page. +> +> Samples of the **Experimental**, **Deprecated**, and **Non-standard** banners are shown right after this note block. > > --- > @@ -72,7 +76,7 @@ browser-compat: css.properties.NameOfTheProperty > > _Remember to remove this note block before publishing._ -{{SeeCompatTable}}{{deprecated_header}}{{CSSRef}} +{{CSSRef}}{{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}} Begin the content on the page with an introductory paragraph, which names the property and says what it does. This should ideally be one or two short sentences. diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_selector_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_selector_page_template/index.md index 443dd15f452d059..47ff237bc7af930 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_selector_page_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_selector_page_template/index.md @@ -30,7 +30,7 @@ browser-compat: css.selectors.NameOfTheSelector > ``` > > - **title** -> - : Title heading displayed at top of page. Format as _:NameOfTheSelector_. +> - : Title heading displayed at the top of the page. Format as _:NameOfTheSelector_. > For example, the [`:hover`](/en-US/docs/Web/CSS/:hover) selector has a title of _:hover_. > - **slug** > - : The end of the URL path after `https://developer.mozilla.org/en-US/docs/`). This will be formatted like `Web/CSS/:NameOfTheSelector`. @@ -38,7 +38,7 @@ browser-compat: css.selectors.NameOfTheSelector > - **page-type** > - : The `page-type` key for CSS properties is one of `css-selector`, `css-pseudo-class`, or `css-pseudo-element`, depending on whether the selector is a [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes), a [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements), a [combinator](/en-US/docs/Web/CSS/CSS_selectors/Selectors_and_combinators#combinators), or a [basic selector](/en-US/docs/Web/CSS/CSS_selectors/Selector_structure#basic_selectors). > - **status** -> - : Include (appropriate) technology status keys: [**experimental**](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental), [**deprecated**](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated), **non-standard** (if not on a standards track). +> - : Flags describing the status of this feature. An array which may contain one or more of the following: `experimental`, `deprecated`, `non-standard`. This key should not be set manually: it is set automatically based on values in the browser compatibility data for the feature. See ["How to add or update feature statuses"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses). > - **browser-compat** > > - : Replace the placeholder value css.selectors.NameOfTheSelector with the query string for the selector in the [Browser compat data repo](https://github.com/mdn/browser-compat-data). @@ -52,29 +52,35 @@ browser-compat: css.selectors.NameOfTheSelector > **Top-of-page macros** > > A number of macro calls appear at the top of the content section (immediately below the page frontmatter). -> You should update or delete them according to the advice below: +> These macros are automatically added by the toolchain (there is no need to add/remove): > > - `\{{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). -> If the technology you are documenting is not experimental, you can remove this. > If it is experimental, and the technology is hidden behind a pref in Firefox, you should also fill in an entry for it in the [Experimental features in Firefox](/en-US/docs/Mozilla/Firefox/Experimental_features) page. > - `\{{Deprecated_Header}}` — this generates a **Deprecated** banner that indicates that use of the technology is [discouraged](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated). -> If it isn't, then you can remove the macro call. +> - `\{{Non-standard_Header}}` — this generates a **Non-standard** banner that indicates that the feature is not part of any specification. +> +> You should update or delete the following macros according to the advice below: +> > - `\{{CSSRef}}` — this must be present on every CSS selector page. It generates a suitable CSS sidebar, depending on what tags are included on the page. > Remember to remove the `\{{MDNSidebar}}` macro when you copy this page. > +> Do not provide status header macros manually. Refer to the section ["How to add or update feature statuses"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses) to add these statuses to the page. +> +> Samples of the **Experimental**, **Deprecated**, and **Non-standard** banners are shown right after this note block. +> > --- > > **Syntax section (`\{{CSSSyntax}}`)** > > The content of the Syntax section is generated using the `\{{CSSSyntax}}` macro. -> For these to populate you must ensure an appropriate entry has been filled in for the selector in our [selectors.json](https://github.com/mdn/data/blob/main/css/selectors.json) data file. +> For these to populate, you must ensure an appropriate entry has been filled in for the selector in our [selectors.json](https://github.com/mdn/data/blob/main/css/selectors.json) data file. > See [selectors.md](https://github.com/mdn/data/blob/main/css/selectors.md) for more information. > > _Remember to remove this whole explanatory note before publishing_ -{{CSSRef}}{{SeeCompatTable}}{{Deprecated_Header}} +{{CSSRef}}{{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}} -The summary paragraph — start by naming the selector and saying what it does. This should ideally be 1 or 2 short sentences. +The summary paragraph — start by naming the selector and saying what it does. This should ideally be one or two short sentences. ```css /* Insert code block showing common use cases */ diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/html_element_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/html_element_page_template/index.md index 992af1cbcfb72be..80e1c84032d26c0 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/html_element_page_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/html_element_page_template/index.md @@ -30,7 +30,7 @@ browser-compat: path.to.feature.NameOfTheElement > ``` > > - **title** -> - : Title heading displayed at top of page. +> - : Title heading displayed at the top of the page. > Format as `': Description of element's purpose'`. > For example, the [`