Affected URL(s)

https://nodejs.org/api/fs.html#filehandlewritebuffer-offset-length-position, https://nodejs.org/api/fs.html#fsreadfd-buffer-offset-length-position-callback, https://nodejs.org/api/fs.html#fsmkdirpath-options-callback, https://nodejs.org/api/fs.html#fsrmdirpath-options-callback, https://nodejs.org/api/fs.html#fschmodpath-mode-callback, https://nodejs.org/api/fs.html#fsreadfilepath-options-callback

Description of the problem

Summary

While reviewing the fs and fs/promises documentation, I found several small but important documentation issues related to formatting, consistency, and missing clarifications. These are not code bugs — only documentation fixes.

1. Formatting Error in filehandle.write()

Current: Default:pwrite(2)null
Expected: Default: null (See pwrite(2))
→ Markdown rendering error; link and default value merged together.

2. Inconsistent Default Formatting

Some parameters show Default::null (double colon) instead of Default: null.
Occurs in multiple methods across fs.

3. Missing EOF Clarification in fs.read()

bytesRead can be 0 to indicate end-of-file, but this is not stated in the parameter description — only implied later in text.

4. Ambiguous Deprecation for recursive Option

In fs.rmdir() and fs.mkdir(), the recursive option is marked as Deprecated, but:

• No version is mentioned
• No alternative (fs.rm() / fs.mkdir({ recursive: true })) is provided
• No note if it’s still safe to use

5. Missing Cross-Link for File Modes

The “File modes” table appears only under fs.chmod() but applies to multiple APIs like fs.open(), fs.mkdir(), etc.
Suggestion: Add “See also: File modes” links in related methods.

6. Performance Warning Placement in fs.readFile()

Performance warning about reading large files is buried at the end after examples.
Suggestion: Move it higher or highlight as “⚠️ Performance note” near the top.

All these are low-risk, documentation-only improvements that enhance clarity and developer experience.
I’m happy to submit PRs if needed.