New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat(doc): Add warning blocks to API docs #52743
Comments
We already use |
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. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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)
, andborder-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.The text was updated successfully, but these errors were encountered: