docs(remark-includes): update for path resolution and usage

Update the README to clarify how include paths are resolved when processing in-memory strings, consolidate usage examples, and document directive requirements and error handling behavior.

Assisted-by: GPT-5-3

---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
  - task: lint_filenames
    status: passed
  - task: lint_editorconfig
    status: passed
  - task: lint_markdown
    status: passed
  - task: lint_package_json
    status: na
  - task: lint_repl_help
    status: na
  - task: lint_javascript_src
    status: na
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: na
  - task: lint_javascript_tests
    status: na
  - task: lint_javascript_benchmarks
    status: na
  - task: lint_python
    status: na
  - task: lint_r
    status: na
  - task: lint_c_src
    status: na
  - task: lint_c_examples
    status: na
  - task: lint_c_benchmarks
    status: na
  - task: lint_c_tests_fixtures
    status: na
  - task: lint_shell
    status: na
  - task: lint_typescript_declarations
    status: passed
  - task: lint_typescript_tests
    status: na
  - task: lint_license_headers
    status: passed
---

Author: batpigandme

lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/README.md

@@ -37,17 +37,24 @@ Attaches a plugin to a [remark][remark] processor in order to insert content fro
 <!-- eslint-disable node/no-sync -->
 
 ```javascript
+var join = require( 'path' ).join;
 var remark = require( 'remark' );
 
+var opts = {
+    'dir': join( __dirname, 'snippets' )
+};
+
 var str = '# Hello World!\n';
 str += '\n';
-str += '<!-- <include path="./docs/snippets/foo.md"> -->\n';
+str += '<!-- <include path="./foo.md"> -->\n';
 str += '\n';
 str += '<!-- </include> -->\n';
 
-var vfile = remark().use( includes ).processSync( str );
+var vfile = remark().use( includes, opts ).processSync( str );
 ```
 
+By default, include paths are resolved relative to the processed file's directory. Accordingly, when processing an in-memory string without a file path, includes may not be resolved unless a base directory is provided via the `dir` option.
+
 The plugin recognizes HTML comments of the form
 
 ```html
@@ -58,30 +65,16 @@ The plugin recognizes HTML comments of the form
 
 and inserts the parsed Markdown content of the referenced file between the opening and closing comment tags.
 
+The opening include directive requires a `path` attribute with a double-quoted value.
+
 The plugin accepts the following `options`:
 
 -   **dir**: base directory for resolving include paths. Default: `null` (resolved relative to the processed file's directory).
 
-To specify a base directory from which to resolve include paths:
-
-<!-- eslint-disable node/no-sync -->
-
-```javascript
-var remark = require( 'remark' );
-
-var opts = {
-    'dir': '/absolute/path/to/snippets'
-};
-
-var str = '<!-- <include path="./foo.md"> -->\n';
-str += '\n';
-str += '<!-- </include> -->\n';
-
-var vfile = remark().use( includes, opts ).processSync( str );
-```
-
 If a referenced file cannot be found, the plugin issues a warning and leaves the include block unchanged.
 
+If an opening include directive does not have a matching closing include directive, the plugin issues a warning and leaves the include block unchanged.
+
 </section>
 
 <!-- /.usage -->