|
| 1 | +--- |
| 2 | +title: HTML attribute page template |
| 3 | +slug: MDN/Writing_guidelines/Page_structures/Page_types/HTML_attribute_page_template |
| 4 | +page-type: mdn-writing-guide |
| 5 | +sidebar: mdnsidebar |
| 6 | +--- |
| 7 | + |
| 8 | +HTML attributes fall into two categories: **element-specific attributes**, which apply only to certain elements (e.g., the `accept` attribute on `<input type="file">`), and **global attributes** which can be used for any HTML element (e.g., `class`, `id`). The former should be put under `HTML/Reference/Attributes`, while the latter should be put under `HTML/Reference/Global_attributes`. |
| 9 | + |
| 10 | +Note that most element-specific attributes don't need standalone articles if the attribute list in the element reference is sufficient to describe its behavior. |
| 11 | +Only add an article if the attribute has enough nuance to deserve its own examples, or it is a global attribute. |
| 12 | + |
| 13 | +> **Note:** _Remove this whole explanatory note before publishing_ |
| 14 | +> |
| 15 | +> --- |
| 16 | +> |
| 17 | +> **Page front matter:** |
| 18 | +> |
| 19 | +> The frontmatter at the top of the page is used to define "page metadata". |
| 20 | +> The values should be updated appropriately for the particular attribute. |
| 21 | +> |
| 22 | +> ```md |
| 23 | +> --- |
| 24 | +> title: name-of-the-attribute |
| 25 | +> slug: Web/HTML/Reference/Global_attributes/name-of-the-attribute |
| 26 | +> page-type: html-attribute |
| 27 | +> status: |
| 28 | +> - deprecated |
| 29 | +> - experimental |
| 30 | +> - non-standard |
| 31 | +> browser-compat: html.global_attributes.name-of-the-attribute |
| 32 | +> sidebar: htmlsidebar |
| 33 | +> --- |
| 34 | +> ``` |
| 35 | +> |
| 36 | +> - **title** |
| 37 | +> - : Title heading displayed at the top of the page. |
| 38 | +> Format as `name-of-the-attribute` (just the attribute name itself). |
| 39 | +> For example, the [`class`](/en-US/docs/Web/HTML/Reference/Global_attributes/class) attribute has a _title_ of `class`. |
| 40 | +> - **slug** |
| 41 | +> - : The end of the URL path after `https://developer.mozilla.org/en-US/docs/`. |
| 42 | +> This will be formatted like `Web/HTML/Reference/Global_attributes/name-of-the-attribute` or `Web/HTML/Reference/Attributes/name-of-the-attribute`, where the attributes name is in _lower case_. |
| 43 | +> For example, the [`class`](/en-US/docs/Web/HTML/Reference/Global_attributes/class) attribute has a _slug_ of `Web/HTML/Reference/Global_attributes/class`. |
| 44 | +> - **page-type** |
| 45 | +> - : Always `html-attribute`. |
| 46 | +> - **status** |
| 47 | +> - : 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 feature statuses are added or updated"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_feature_statuses_are_added_or_updated). |
| 48 | +> - **browser-compat** |
| 49 | +> |
| 50 | +> - : Replace the placeholder value `html.global_attributes.name-of-the-attribute` with the query string for the global attribute in the [Browser compat data repo](https://github.com/mdn/browser-compat-data). |
| 51 | +> For element-specific attributes, use the format `html.elements.name-of-the-element.name-of-the-attribute`, with each query string on its own line, preceded by a dash. For example: |
| 52 | +> |
| 53 | +> ```yaml |
| 54 | +> browser-compat: |
| 55 | +> - html.elements.form.autocomplete |
| 56 | +> - html.elements.input.autocomplete |
| 57 | +> - html.elements.select.autocomplete |
| 58 | +> - html.elements.textarea.autocomplete |
| 59 | +> ``` |
| 60 | +> |
| 61 | +> The toolchain automatically uses the key to populate the compatibility and specification sections (replacing the `\{{Compat}}` and `\{{Specifications}}` macros). |
| 62 | +> Note that you may first need to create/update an entry for the attribute in our [Browser compat data repo](https://github.com/mdn/browser-compat-data), and the entry will need to include specification information. |
| 63 | +> See our [guide on how to do this](/en-US/docs/MDN/Writing_guidelines/Page_structures/Compatibility_tables). |
| 64 | +> |
| 65 | +> - **sidebar** |
| 66 | +> - : Keep as `htmlsidebar` (all pages under `/web/html/` use this sidebar). |
| 67 | +> See [Page structures: Sidebars](/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars) for details. |
| 68 | +> |
| 69 | +> --- |
| 70 | +> |
| 71 | +> **Top-of-page macros** |
| 72 | +> |
| 73 | +> A number of macro calls appear at the top of the content section (immediately below the page frontmatter). |
| 74 | +> These macros are automatically added by the toolchain (there is no need to add/remove): |
| 75 | +> |
| 76 | +> - `\{{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). |
| 77 | +> 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. |
| 78 | +> - `\{{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). |
| 79 | +> - `\{{Non-standard_Header}}` — this generates a **Non-standard** banner that indicates that the feature is not part of any specification. |
| 80 | +> |
| 81 | +> Do not provide status header macros manually. Refer to the section ["How feature statuses are added or updated"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_feature_statuses_are_added_or_updated) to add these statuses to the page. |
| 82 | +> |
| 83 | +> Samples of the **Experimental**, **Deprecated**, and **Non-standard** banners are shown right after this note block. |
| 84 | +> |
| 85 | +> _Remember to remove this whole explanatory note before publishing_ |
| 86 | +> |
| 87 | +> {{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}} |
| 88 | +> |
| 89 | +> Start by introducing the reader to the attribute, and its usage. |
| 90 | +> For example: The **`name-of-the-attribute`** [global attribute](/en-US/docs/Web/HTML/Reference/Global_attributes) describes or manipulates [insert usage description]. |
| 91 | +
|
| 92 | +## Try it |
| 93 | +
|
| 94 | +This section is generated by the `InteractiveExample` macro. |
| 95 | +This includes the "Try it" section title and the code editor. |
| 96 | +See the [Interactive examples](/en-US/docs/MDN/Writing_guidelines/Page_structures/Code_examples#interactive_examples) section in our _Writing guidelines_ for more information. |
| 97 | +If included, follow it with 1-2 brief paragraphs explaining the behavior implemented, and optionally highlighting any interaction with JavaScript, CSS, or other attributes. Keep it concise and avoid duplicating full docs — link out what needed. Again, see the `class` attribute page. |
| 98 | +
|
| 99 | +## Values |
| 100 | +
|
| 101 | +Provide a list of possible values for the attribute if any (remove if not applicable). Include the default value if there is one, and a brief description for each value. |
| 102 | +
|
| 103 | +- `value 1` |
| 104 | + - : Description of value 1. This is the Default value. |
| 105 | +- `value 2` |
| 106 | + - : Description of value 2. |
| 107 | +- `value 3` |
| 108 | + - : Description of value 3. |
| 109 | +
|
| 110 | +## Accessibility |
| 111 | +
|
| 112 | +Warn of any potential accessibility concerns that may exist with using this attribute, and how to work around them. Remove this section if there are none to list. |
| 113 | +
|
| 114 | +## Examples |
| 115 | +
|
| 116 | +Show relevant examples for this attribute, and how to use this attribute in practical HTML contexts. |
| 117 | +Note that we use the plural "Examples" even if the page only contains one example. |
| 118 | +
|
| 119 | +### A descriptive heading |
| 120 | +
|
| 121 | +Each example must have an H3 heading (`###`) highlighting the example. The heading should be descriptive of what the example is doing. For example, "A simple example" does not say anything about the example and therefore, not a good heading. The heading should be concise. For a longer description, use the paragraph after the heading. |
| 122 | +See our guide on how to add [code examples](/en-US/docs/MDN/Writing_guidelines/Page_structures/Code_examples) for more information. |
| 123 | +
|
| 124 | +> [!NOTE] |
| 125 | +> Sometimes you will want to link to examples given on another page. |
| 126 | +> |
| 127 | +> **Case 1:** If you have some examples on this page and some more examples on another page: |
| 128 | +> |
| 129 | +> Include an H3 heading (`###`) for each example on this page and then a final H3 heading (`###`) with the text "More examples", under which you can link to the examples on other pages. For example: |
| 130 | +> |
| 131 | +> ```md |
| 132 | +> ## Examples |
| 133 | +> |
| 134 | +> ### Using the `for` attribute |
| 135 | +> |
| 136 | +> Example of `for` attribute |
| 137 | +> |
| 138 | +> ### More examples |
| 139 | +> |
| 140 | +> Links to more examples on other pages |
| 141 | +> ``` |
| 142 | +> |
| 143 | +> **Case 2:** If you _only_ have examples on another page and none on this page: |
| 144 | +> |
| 145 | +> Don't add any H3 headings; just add the links directly under the H2 heading "Examples". For example: |
| 146 | +> |
| 147 | +> ```md |
| 148 | +> ## Examples |
| 149 | +> |
| 150 | +> For examples of this attribute, see [the page on `for` attribute](https://example.org/). |
| 151 | +> ``` |
| 152 | +
|
| 153 | +## Specifications |
| 154 | +
|
| 155 | +`\{{Specifications}}` |
| 156 | +_To use this macro, remove the backticks and backslash in the markdown file._ |
| 157 | +
|
| 158 | +## Browser compatibility |
| 159 | +
|
| 160 | +`\{{Compat}}` |
| 161 | +_To use this macro, remove the backticks and backslash in the markdown file._ |
| 162 | +
|
| 163 | +## See also |
| 164 | +
|
| 165 | +Include links to reference pages and guides related to the current attribute. For more guidelines, see the [See also section](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide#see_also_section) in the _Writing style guide_. |
| 166 | +
|
| 167 | +- link1 |
| 168 | +- link2 |
| 169 | +- external_link (year) |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments