Skip to content
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

Closed
akuankka128 opened this issue Apr 29, 2024 · 2 comments
Closed

feat(doc): Add warning blocks to API docs #52743

akuankka128 opened this issue Apr 29, 2024 · 2 comments
Labels
doc Issues and PRs related to the documentations. security Issues and PRs related to security.

Comments

@akuankka128
Copy link

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:
Documentation before proposed change

After proposed change:
Documentation after proposed change, showing an orange warning block with text

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.

@VoltrexKeyva VoltrexKeyva added the doc Issues and PRs related to the documentations. label Apr 29, 2024
@RedYetiDev RedYetiDev added the security Issues and PRs related to security. label Apr 29, 2024
@tniessen
Copy link
Member

tniessen commented May 9, 2024

We already use <strong class="critical"> in various places. Maybe we can just rework that style a little bit.

@RedYetiDev
Copy link
Member

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
Labels
doc Issues and PRs related to the documentations. security Issues and PRs related to security.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants