HTML attributes section

[estelle]

The HTML attributes page has many broken or missing links, is difficult to maintain,

We have two HTML attribute subtrees:

1. https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes
2. https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes

The global attributes page is fairly well maintained, with no attribute being added to the page unless there is a subpage. It also makes sense to have pages for each individual global attribute as they are, well, global. Other attributes may be valid on a subset of elements, or just a single element.

It makes sense to create an attribute page for an element used with all or several elements if they have the same use in each of those elements - that removes a lot of content repetition in multiple element pages and helps with maintenance. It is also good to put element exceptions those pages so devs know that an atttibute may not be used the same way on each element that accepts it as an attribute.

It doesn't make sense to create a full page for a basic attribute only relevant to one element. If we have a list of "most HTML attributes", if an attribute is used in one or two elements, we can provide a brief definition and link to the description in both pages.

The main conundrum comes from attributes that are in several pages, with different effects based on the HTML element on which it is used.

there is a table of attributes entitled HTML attribute reference at https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes. The list is incomplete both in terms of there being missing attributes (over 10 global attributes are missing from the list) and in terms of there being red non-links due to missing documentation. We get a lot of issues for this page, and for the attribute pages in the subtree.

Suggested fixes:

1. Convert the page from a refernce to a guide
2. remove the table
3. Put in a definition list limited to the attributes that have pages both in the attributes sub-tree (https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/) and the global attributes sub-tree (https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/). List these in alphabetical order, as currently done, but with the list of obsolete and deprecated attributes coming after a main list.
4. Add text clarifying that this is not an exhaustive list of all attributes

For the DL of attributes:

DT:

• The DT should be the attribute
• If the attribute is only valid for one element, the attribute in the DT should link to the attribute section in the relevant HTML file.
• If there is an attribte page, the DT should link to the attribute page (should there be a page is another question)
• If the attribute is valid for a few attributes, and there is no page, the DT should not be a link. Rather, the list of elements supporting that attribute id the DD should each link to the attribute within each element's page.

DD

• The DD should briefly describe what the attribute does.
• The DD should list which elements support the attribute, if fewer than X (What should X be?)
• If the attribute behaves differently for some elements, the first sentence should be the general use case, with exceptions following.

Some PRs:

• No mention of "as" attribute content#31960
• HTML attribute reference list is incomplete content#32229 (contains a list of all attributes, i think)
• Create a form attribute page content#28375
• Page not found errors on HTML attribute reference page content#27733

[Rumyra]

For additional info - this page ranks pretty high for sentiment usefulness (over 0.8) so I agree keeping it and making it even more useful sounds like a great idea.

I also support this plan - it sounds good @estelle 👍

[Josh-Cena]

If the attribute is valid for a few attributes, and there is no page, the DT should not be a link. Rather, the list of elements supporting that attribute id the DD should each link to the attribute within each element's page.

Doesn't that mean it would not be part of the DL in this case, since you also said the DL should only list things actually in the subtree (which I completely agree)?

[Akindin]

It is also helpful while inspecting codebase of a project to distinct custom attributes from the ones coming from pure HTML

[Josh-Cena]

All custom attributes must be prefixed with data-. You are not allowed to put unknown attributes on HTML elements. See HTML spec:

Authors must not use elements, attributes, or attribute values that are not permitted by this specification or other applicable specifications, as doing so makes it significantly harder for the language to be extended in the future.

[Akindin]

From experience I could say that even deprecated attributes are worth knowing for example in markup for mail services which doesn't support a lot of common css properties

[Josh-Cena]

The HTML element reference already lists all possible attributes including deprecated ones. The relationship between elements and attributes are more like a tree than a grid (except for maybe form elements), which is why a standalone "attributes" reference doesn't make sense without putting them into the context of each element.

[bencemeszaros]

I have made a cross-reference table of all html elements vs all attributes for easy lookup in both directions. I am not sure whether this is helpful in this discussion or not, but I just wanted to share it just in case:

https://docs.google.com/spreadsheets/d/17C2uGxFI_3y_6p-cl1OFyua6rtdcVsfwpnMsoUhDyes/edit?usp=sharing

It is not fully completed and probably a dumb idea, so please go easy on it.