Add web developer friendly links to MDN

[captainbrosset]

Help wanted: help me complete the mapping between web-features and MDN URLs

The features listed in the web-features repository don't come with MDN URLs.
However, linking web-features to MDN URLs is useful for several things:

• If the mapping is available somewhere, then consumers of web-features can use the mapping to link the web-features they display to MDN.
  • One example is the State Of surveys, which use web-features, and which also show MDN URLs. This mapping with help there.
  • Another example is this very site: https://web-platform-dx.github.io/web-features-explorer/, which shows MDN links on individual feature pages. This mapping helps show the right links.
• The other way around is true too. For MDN, which shows baseline badges, having a one-to-one mapping from MDN pages to web-features can help find the right web-features.

The mapping is, for now, maintained in this file: https://github.com/web-platform-dx/web-features-explorer/blob/main/mdnDocsOverrides.json

There are still a couple hundred features left to be mapped. Here's how the mapping works:

{
  "<web-feature-id>": [
    "<MDN-page-slug>"
  ]
}

Each feature points to one or more MDN URL. Each MDN URL is partial, only the slug is needed, not the root URL. Here's an example:

{
  "aborting": [
    "Web/API/AbortController",
    "Web/API/AbortSignal"
  ]
}

The root URL is https://developer.mozilla.org/en-US/docs/, so the two slugs above end up pointing to: https://developer.mozilla.org/en-US/docs/Web/API/AbortController and https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal.

On the web-features-explorer website, currently, the mapping is used to display links as follows:

See this page live here: https://web-platform-dx.github.io/web-features-explorer/features/aborting/

[jsnkuhn]

If this is really as straightforward as it seems I'll give this some time. Searching for and then copy/pasting links into the .json is all you are really looking for here?

[captainbrosset]

Pretty much, yes. It takes a little bit of reading of the feature description first, to make sure you know what the feature is about. And it takes a little bit of figuring out whether we want just one link to MDN (which is the most common case), or several (e.g. when a feature is about, say, two different methods that are related, but that are not described by just one MDN page).

Thank you for helping !

[jsnkuhn]

Before I get too far along. I see a listing for "borders" that links to the border MDN article.

• should that be changed to "border" because that's official the property name?
• should I add the shorthand properties (border-style,border-color etc) to this as well. And if so how? Should they be separate properties and/or all listed under the "border(s)" entry.

[captainbrosset]

The object keys in that file correspond to IDs of features defined in the web-features repository. They should not be changed.

To find out more about a feature, given its ID, do either of these things:

• Go to https://github.com/web-platform-dx/web-features and look for the file in the features folder that has the same name as the feature ID. For example, borders.yml.
• Or open the feature on the explorer website: https://web-platform-dx.github.io/web-features-explorer/features/borders (replace the last part with your feature ID).

For this project, you should consider the feature IDs as fixed and should not change them in the mdnDocsOverrides.json file. The idea is, for each feature listed in there to find the MDN page that best describes the feature.

Does that help ?

[jsnkuhn]

Yes, thank you that helps. Had a go at A-C this afternoon. Have a look and let me know if I'm on the right track before I send a pull:

main...jsnkuhn:web-features-explorer:main

Do you want them all at once or is it fine in sections like this one?

[captainbrosset]

@jsnkuhn looks like a great start. Please do send a pull request. And, yes, in sections like this one is best. It'll make it easier to review.

[jsnkuhn]

Dropping this in here as a reminder to jump ahead to the things listed on "CSS Wrapped 2024" that need MDN links before going back to working alphabetically. Will watch out for anything similar from the other vendors:

https://chrome.dev/css-wrapped-2024/

[jsnkuhn]

Most of the Wrapped 2024 stuff was already covered but is there really no MDN documentation of ::details-content yet? Seems odd that there wouldn't be any yet with it being live in chromium for a month already?

[captainbrosset]

It's coming apparently : mdn/content#37118