Duplicate IDs: can they be helped?

Josh-Cena commented 3 months ago

Summary

Sometimes, content generated by macros can have IDs that duplicate with what's already on the page. This makes the HTML invalid. I'm not sure if it can be helped, but just want to discuss because they are discovered by my checker.

URL

I have discovered 15 cases of duplicate IDs:

files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md
  Duplicate ID frame_iframe_size
  Duplicate ID frame_allowing_features
files/en-us/web/api/css_object_model/managing_screen_orientation/index.md
  Duplicate ID frame_adjusting_layout_based_on_the_orientation
files/en-us/web/css/@property/syntax/index.md
  Duplicate ID syntax
files/en-us/web/css/calc-sum/index.md
  Duplicate ID <calc-sum>
files/en-us/web/css/color/index.md
  Duplicate ID color
files/en-us/web/css/container-name/index.md
  Duplicate ID container-name
files/en-us/web/css/inset-area/index.md
  Duplicate ID inset-area
files/en-us/web/css/offset/index.md
  Duplicate ID <offset-path>
files/en-us/web/css/offset-path/index.md
  Duplicate ID offset-path
files/en-us/web/css/position-try/index.md
  Duplicate ID <inset-area>
files/en-us/web/css/position-try-fallbacks/index.md
  Duplicate ID <inset-area>
files/en-us/web/css/scrollbar-color/index.md
  Duplicate ID scrollbar-color
files/en-us/web/css/scrollbar-width/index.md
  Duplicate ID scrollbar-width
files/en-us/web/mathml/element/mfenced/index.md
  Duplicate ID frame_mfenced_example1

Reproduction steps

Go to one of the pages above, such as https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Live_samples, and in the console type document.querySelectorAll("#frame_iframe_size"). See that the list contains more than one item.

Expected behavior

IDs are globally unique

Actual behavior

IDs are not globally unique.

The reports can be divided into several cases:

Multiple EmbedLiveSamples that use the same ID. I'm not sure why the iframe needs an ID at all; maybe we can just remove it. Otherwise we should have a parameter that sets the ID for the iframe.
CSS formal syntax clashes with other items on the page. For example, on https://developer.mozilla.org/en-US/docs/Web/CSS/offset-path, offset-path is both a dl item and a formal syntax symbol.
CSS formal syntax that contains duplicate symbols. This looks like a Yari bug, or a data bug. For example on https://developer.mozilla.org/en-US/docs/Web/CSS/calc-sum, <calc-sum> appears twice in the syntax. On https://developer.mozilla.org/en-US/docs/Web/CSS/offset, <offset-path> appears twice, and with different expansions. Maybe it's pulling from multiple specs.

I think, in general, we may be able to fix this by post-processing the HTML file and adding suffixes if IDs collide, but just want to bring it to your attention for discussion.

Device

Desktop

Browser

Chrome

Browser version

Stable

Operating system

Mac OS

Screenshot

No response

Anything else?

https://github.com/mdn/yari/issues/5913 is a similar issue but not duplicate. I don't actually care about the final rendered MDN page; I only care about the content HTML, so if there are duplicate IDs in the site layout I won't report them.

Validations

[X] I have read the Community Participation Guidelines.
[X] I have verified that there isn't already an issue that reports the same bug to avoid creating a duplicate.
[X] I have checked that this is a concrete bug. For Q&A open a GitHub Discussion.

OnkarRuikar commented 1 month ago

Multiple EmbedLiveSamples that use the same ID.

In markdownlint we do have no-duplicate-heading enabled but we allow duplicates under different parent headers. Can we make the rule more strict? i.e. no duplicate headings at all. We can write a custom markdown lint rule that will flag all the duplicate headers except HTML, CSS, JS, Result etc. This will prevent two EmbedLivesample macros using same header.

For example on developer.mozilla.org/en-US/docs/Web/CSS/calc-sum, appears twice in the syntax ... Maybe it's pulling from multiple specs.

It is a bug because both the syntaxes have recursion in them. The syntax rendering code needs to check if the value/type has already been expanded.

Josh-Cena commented 1 month ago

Please don't forbid duplicate headings... This is a platform problem. Not a content problem.

mdn / yari