doc: add 'not recommended' blockquotes

doc/api/crypto.md

@@ -5551,10 +5551,10 @@ instead.
 
 ### Support for weak or compromised algorithms
 
-The `node:crypto` module still supports some algorithms which are already
-compromised and are not recommended for use. The API also allows
-the use of ciphers and hashes with a small key size that are too weak for safe
-use.
+> Warning: The `node:crypto` module still supports some algorithms which are already
+> compromised and are not recommended for use. The API also allows
+> the use of ciphers and hashes with a small key size that are too weak for safe
+> use.
 
 Users should take full responsibility for selecting the crypto
 algorithm and key size according to their security requirements.

doc/api/fs.md

@@ -898,11 +898,11 @@ try {
 }
 ```
 
-Using `fsPromises.access()` to check for the accessibility of a file before
-calling `fsPromises.open()` is not recommended. Doing so introduces a race
-condition, since other processes may change the file's state between the two
-calls. Instead, user code should open/read/write the file directly and handle
-the error raised if the file is not accessible.
+> Warning: Using `fsPromises.access()` to check for the accessibility of a file before
+> calling `fsPromises.open()` is not recommended. Doing so introduces a race
+> condition, since other processes may change the file's state between the two
+> calls. Instead, user code should open/read/write the file directly and handle
+> the error raised if the file is not accessible.
 
 ### `fsPromises.appendFile(path, data[, options])`
 
@@ -1981,11 +1981,11 @@ access(file, constants.R_OK | constants.W_OK, (err) => {
 });
 ```
 
-Do not use `fs.access()` to check for the accessibility of a file before calling
-`fs.open()`, `fs.readFile()`, or `fs.writeFile()`. Doing
-so introduces a race condition, since other processes may change the file's
-state between the two calls. Instead, user code should open/read/write the
-file directly and handle the error raised if the file is not accessible.
+> Warning: Do not use `fs.access()` to check for the accessibility of a file before calling
+> `fs.open()`, `fs.readFile()`, or `fs.writeFile()`. Doing
+> so introduces a race condition, since other processes may change the file's
+> state between the two calls. Instead, user code should open/read/write the
+> file directly and handle the error raised if the file is not accessible.
 
 **write (NOT RECOMMENDED)**
 
@@ -2741,11 +2741,11 @@ parameter, optionally followed by other parameters. The `fs.exists()` callback
 has only one boolean parameter. This is one reason `fs.access()` is recommended
 instead of `fs.exists()`.
 
-Using `fs.exists()` to check for the existence of a file before calling
-`fs.open()`, `fs.readFile()`, or `fs.writeFile()` is not recommended. Doing
-so introduces a race condition, since other processes may change the file's
-state between the two calls. Instead, user code should open/read/write the
-file directly and handle the error raised if the file does not exist.
+> Warning: Using `fs.exists()` to check for the existence of a file before calling
+> `fs.open()`, `fs.readFile()`, or `fs.writeFile()` is not recommended. Doing
+> so introduces a race condition, since other processes may change the file's
+> state between the two calls. Instead, user code should open/read/write the
+> file directly and handle the error raised if the file does not exist.
 
 **write (NOT RECOMMENDED)**
 
@@ -4310,10 +4310,10 @@ In case of an error, the `err.code` will be one of [Common System Errors][].
 [`fs.stat()`][] follows symbolic links. Use [`fs.lstat()`][] to look at the
 links themselves.
 
-Using `fs.stat()` to check for the existence of a file before calling
-`fs.open()`, `fs.readFile()`, or `fs.writeFile()` is not recommended.
-Instead, user code should open/read/write the file directly and handle the
-error raised if the file is not available.
+> Warning: Using `fs.stat()` to check for the existence of a file before calling
+> `fs.open()`, `fs.readFile()`, or `fs.writeFile()` is not recommended.
+> Instead, user code should open/read/write the file directly and handle the
+> error raised if the file is not available.
 
 To check if a file exists without manipulating it afterwards, [`fs.access()`][]
 is recommended.

doc/api_assets/style.css

@@ -328,6 +328,15 @@ li.picker-header a span {
  background-color: var(--blue1);
 }
 
+.api_warning {
+ border: 5px solid var(--red2);
+ border-radius: 5px;
+ color: var(--white) !important;
+ margin: 0 0 1rem;
+ padding: 1rem;
+ line-height: 1.5;
+}
+
 .module_stability {
  vertical-align: middle;
 }

tools/doc/html.mjs

@@ -276,44 +276,57 @@ export function preprocessElements({ filename }) {
  node.children[0];
  const text = paragraph && paragraph.children[0].type === 'text' &&
  paragraph.children[0];
- if (text && text.value.includes('Stability:')) {
- const [, prefix, number, explication] =
- text.value.match(STABILITY_RE);
-
- // Stability indices are never more than 3 nodes away from their
- // heading.
- const isStabilityIndex = index - headingIndex <= 3;
-
- if (heading && isStabilityIndex) {
- heading.stability = number;
- headingIndex = -1;
- heading = null;
+ if (text) {
+ if (text.value.includes('Stability:')) {
+ const [, prefix, number, explication] =
+ text.value.match(STABILITY_RE);
+
+ // Stability indices are never more than 3 nodes away from their
+ // heading.
+ const isStabilityIndex = index - headingIndex <= 3;
+
+ if (heading && isStabilityIndex) {
+ heading.stability = number;
+ headingIndex = -1;
+ heading = null;
+ }
+
+ // Do not link to the section we are already in.
+ const noLinking = filename.includes('documentation') &&
+ heading !== null && heading.children[0].value === 'Stability index';
+
+ // Collapse blockquote and paragraph into a single node
+ node.type = 'paragraph';
+ node.children.shift();
+ node.children.unshift(...paragraph.children);
+
+ // Insert div with prefix and number
+ node.children.unshift({
+ type: 'html',
+ value: `<div class="api_stability api_stability_${number}">` +
+ (noLinking ? '' :
+ '<a href="documentation.html#stability-index">') +
+ `${prefix} ${number}${noLinking ? '' : '</a>'}`
+ .replace(/\n/g, ' '),
+ });
+
+ // Remove prefix and number from text
+ text.value = explication;
+
+ // close div
+ node.children.push({ type: 'html', value: '</div>' });
+ } else if (text.value.includes('Warning:')) {
+ node.type = 'paragraph';
+ node.children.shift();
+ node.children.unshift(...paragraph.children);
+ text.value = text.value.replace(/^Warning:\s*/, '');
+ node.children.unshift({ type: 'html', value: '<strong>Warning:</strong> ' });
+ node.children.unshift({
+ type: 'html',
+ value: '<div class="api_warning">',
+ });
+ node.children.push({ type: 'html', value: '</div>' });
  }
-
- // Do not link to the section we are already in.
- const noLinking = filename.includes('documentation') &&
- heading !== null && heading.children[0].value === 'Stability index';
-
- // Collapse blockquote and paragraph into a single node
- node.type = 'paragraph';
- node.children.shift();
- node.children.unshift(...paragraph.children);
-
- // Insert div with prefix and number
- node.children.unshift({
- type: 'html',
- value: `<div class="api_stability api_stability_${number}">` +
- (noLinking ? '' :
- '<a href="documentation.html#stability-index">') +
- `${prefix} ${number}${noLinking ? '' : '</a>'}`
- .replace(/\n/g, ' '),
- });
-
- // Remove prefix and number from text
- text.value = explication;
-
- // close div
- node.children.push({ type: 'html', value: '</div>' });
  }
  }
  });