Highlight deprecated API components in "Table of Contents"

[ilfroloff]

Hello All!

I have a proposal of how to increase understanding on which of properties/methods in module API are deprecated. When someone opens module's API page, he/she sees "Table of Contents" and it's not clear which part is deprecated (especially in util module).

My vision of deprecated parts in "Table of Contents":

CSS for list item:

li.deprecated,
li.deprecated a {
    color: #D60027; // same as backgroud-color of Deprecated box
}

Thanks!

[MylesBorins]

I really like this idea

/cc @nodejs/documentation

@ilfroloff I think you will want to send a PR against the main repo to this file https://github.com/nodejs/node/blob/master/doc/api_assets/style.css

[lpinca]

👍

sounds good, yeah!

[benjamingr]

I think graying it out rather than making it red would be better since red catches the eye.

[Knighton910]

LGTM
+1 GRAY

[steebchen]

What about striking through deprecated lines: deprecated
Or striking through while colored grey?

li.deprecated,
li.deprecated a {
    color: #ccc;
    text-decoration: line-through;
}

[evanlucas]

I think I would like gray. It would be awesome to see some prototypes though

[benjamingr]

@evanlucas sure, run this in the chrome devtools at the production docs and it will strikethrough and change the color of all deprecated APIs.

var links = Array.from(document.querySelectorAll("#toc li a"))
for(const method of links) { // very hacky
  const marker = document.querySelector(method.getAttribute("href"));
  if(!marker) continue;
  const heading = marker.parentNode.parentNode;
  let stability = heading.nextElementSibling;
  if(stability.className === "api_metadata") stability = stability.nextElementSibling; 
  if(stability.className.includes("api_stability_0")) {
     method.style.color = "#999";
     method.style.textDecoration = "line-through";
  }
}

[evanlucas]

thanks @benjamingr. So the link becomes a lot less readable on hover would be my only complaint with that. I'm sure we could fix that quite easily though. I think the best think to do here would be to have a pr with one of these on nodejs/node and we can go from there?

[addaleax]

As much as I would find gray more intuitive, too, I’d be worried that the low contrast from graying out entries might not work out as well as striking through for people with visual impairments. But then again I’m also definitely not an expert on that topic.

[Knighton910]

I was thinking about a dark blue, but at the same time i don't want the docs to look like a rainbow. no offense to rainbows. But something of grey or dark grey or even vanilla white should be fine, i guess.

[benjamingr]

@addaleax that's a good point, #999999 doesn't meat the contrast accessibility standard, we should go with something more like #555555.

[RafaelKr]

As much as I would find gray more intuitive, too, I’d be worried that the low contrast from graying out entries might not work out as well as striking through for people with visual impairments. But then again I’m also definitely not an expert on that topic.

You could make deprecated items grey and add a toogle-button at the top to also strike them through (Or don't show them at all, when button is toggled).