nodejs
feat(doc): Add warning blocks to API docs
I think having just text warnings for potential vulnerabilities relating to the misuse of Node APIs isn't sufficient because they blend in too well. For example, in the documentation for fs.access(), readers might skip past the paragraph about potential race conditions when using the API to check if a file exists and the bold text saying "NOT RECOMMENDED." I suggest that warning blocks be added into the documentation to make it more obvious.
Before proposed change:
After proposed change:
To achieve this, I simply added padding: 1rem, background: rgba(255, 79, 0, 0.5), and border-left: 6pt solid rgb(255, 79, 0) to the paragraph's style. Maybe something similar could be done to the "NOT RECOMMENDED" text too, or maybe the code should even be removed, because what is it there for, anyway? -- Showing the wrong way to be avoided? I don't know how helpful that actually is, so I don't have a strong opinion about it.
We already use <strong class="critical"> in various places. Maybe we can just rework that style a little bit.
As mentioned in #52814, this feature should hopefully be added to the documentation redesign, I'm closing this issue, as this feature will (hopefully) be added. If you disagree, feel free to re-open.
