Add templates for Web Extensions page types#42204
Add templates for Web Extensions page types#42204
Conversation
github-actions
bot
added
Content:Meta
Preview URLs (6 pages)
Flaws (17)Note! 3 documents with no flaws that don't need to be listed. 🎉 URL:
URL:
URL:
(comment last updated: 2025-12-17 14:00:51) |
pepelsbey
force-pushed
the
web-extensions-templates
branch
from
4f14a03 to
1e41eb9
Compare
pepelsbey
force-pushed
the
web-extensions-templates
branch
from
1e41eb9 to
8f7b41b
Compare
rebloor
left a comment
rebloor
left a comment
There was a problem hiding this comment.
@pepelsbey some initial feedback, focusing only on the properties template at the moment. The goal for having commenced this work from the web extensions point of view was to create a mechanism that made it easy for contributions to be made by other browser vendors. As such, having a simple file that can be copied and modified from the repository with prescriptive contact where possible was our goal. Also, the template descriptions repeat advice so, for example, the information on adding examples could be presented once and referenced.
...iting_guidelines/page_structures/page_types/webextension_api_property_page_template/index.md
Outdated
Show resolved
Hide resolved
...iting_guidelines/page_structures/page_types/webextension_api_property_page_template/index.md
Outdated
Show resolved
Hide resolved
| > | ||
| > _Remember to remove this whole explanatory note before publishing._ | ||
|
|
||
| {{SeeCompatTable}}{{Deprecated_Header}} |
There was a problem hiding this comment.
If these macros are added by the toolchain and there's no need to "add or remove them" why are they in the template?
| > - `\{{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). | ||
| > - `\{{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). | ||
| > | ||
| > You should update or delete the following macros according to the advice below: |
There was a problem hiding this comment.
There appears to be only one macro noted, this sentence suggests there are several.
| > - `\{{WebExtAPIRef("GroupDataName")}}` — this generates the left-hand reference sidebar showing quick reference links related to the current page. | ||
| > 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. |
There was a problem hiding this comment.
Don't believe this is correct for web extensions, adding a page to the directory structure with the appropriate font matter determines whether it gets into the sidebar.
| > | ||
| > A number of macro calls appear at the top of the content section (immediately below the page front matter). | ||
| > | ||
| > These macros are automatically added by the toolchain (there is no need to add/remove): |
There was a problem hiding this comment.
I don't believe this information is correct for web extensions, see https://github.com/mdn/browser-compat-data/tree/main/docs/data-guidelines#webextensions-features-do-not-have-status-blocks
webextensions features do not have status blocks
Web extensions are not governed by any specifications and are up to the browser vendors to design and implement. As such, the status blocks would be identical for all web extensions features. Do not add status blocks to the webextensions folder.
This guideline was adopted since the beginning of the project. for example tabs/sendRequest
So, for web extensions, not only does the macro have to be added manually, but the front matter also needs to be manually updating manually. It's worth noting that, in general, rather than using a templated deprecation message, the Web extensions use a specific deprecation message with information about the replacement feature.
|
|
||
| {{SeeCompatTable}}{{Deprecated_Header}} | ||
|
|
||
| Begin the content on the page with an introductory paragraph — start by naming the property, saying what WebExtension namespace it is part of, and saying what it represents and how it is used. |
There was a problem hiding this comment.
start by naming the property, saying what WebExtension namespace it is part of – why? Doesn't the page title already tell you this?
...iting_guidelines/page_structures/page_types/webextension_api_property_page_template/index.md
Outdated
Show resolved
Hide resolved
|
|
||
| Where relevant, describe how the value interacts with other APIs (for example, how to change a setting using a related function). | ||
|
|
||
| ## Examples |
There was a problem hiding this comment.
No mention of {{WebExtExamples}}?
There was a problem hiding this comment.
@pepelsbey overall, but I don't have any particular objection to documenting these templates in this manner, I think it would be more useful to provide a usable template file in the directory, such as /content/templates/webextensions/apis/propertyname with this content (WIP]:
---
title: [API name].[property name]
[comment]: # (sasave the file as index.md in a folder that corresponds to the slug)
slug: Mozilla/Add-ons/WebExtensions/API/[API name]/[property name]
[comment]: # (Add status if the property is deprecated or experimental)
status:
- deprecated
- experimental
page-type: webextension-api-property
browser-compat: webextensions.api.[API name].[property name]
sidebar: addonsidebar
---
[comment]: # (If this property is experimental include:).
{{SeeCompatTable}}
[comment]: # (If this property is deprecated include: ).
> [!WARNING]
> This property is deprecated. Use {{WebExtAPIRef("[API name].[property name]")}} instead.
[comment]: # (If the property is an object, for example, a `BrowserSetting` object.).
A {{WebExtAPIRef([API name].[object name])}} object [description of how the property is used, usually one or two short sentences]
[comment]: # (If the property is a simple value, for example, a number, string, or boolean).
[description of the property, usually one or two short sentences]
[comment]: # (If the value is the same for all browsers).
Its value is `[value]`.
[comment]: # (If the property can take multiple values).
This value is a string whose possible values are:
- val 1
- val 2
- val 3
[comment]: # (If the values vary between browsers).
Its value is:
- in Chrome `[value]`
- in Firefox `[value]`
- in Safari `[value]`
[comment]: # (If the property is read-only.)
This property is read only.
[additional guidance or comments as necessary]
[comment]: # (when ththe property includes properties, methods, or events add these as per the API overview page)
[comment]: # (when there are examples for this page and examples on other pages)
## Examples
### [example title]
[example description]
### More examples
[Links to more examples]
{{WebExtExamples}}
[comment]: # (or, when no examples provided on the page).
## Examples
[Links to more examples]
{{WebExtExamples}}
[comment]: # (or, when no examples provided on this or other pages).
{{WebExtExamples("h2")}}
## Browser compatibility
{{Compat}}
[comment]: # (As required. See the [See also section](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide#see_also_section) in the _Writing style guide_.).
## See also
- link1
- link2
- external_link (year)
There was a problem hiding this comment.
+1 on this. See also: https://github.com/mdn/content/blob/main/scripts/content/release-firefox.md?plain=1 which is another good candidate for a templates dir
Co-authored-by: rebloor <git@sherpa.co.nz>
3 participants
Description
It creates templates for six Web Extension page types:
Templates follow a similar structure but have variations depending on the page type needs.
Motivation
Harmonize Web Extensions docs within the section and with the rest of the MDN reference pages.
To do
{{WebExtExamples}}works