From 21cd8dd2d5926a123660c2a976d0af1d0795ed43 Mon Sep 17 00:00:00 2001
From: Mara Averick <maraaverick@gmail.com>
Date: Thu, 2 Apr 2026 07:37:00 -0600
Subject: [PATCH 1/9] feat(remark-includes): add plugin for external file
 inclusions

Add a remark plugin to insert content from external Markdown files into a document using HTML comment directives. The plugin resolves include paths relative to the file being processed or a specified base directory, parses the external content into AST nodes, and replaces the content between opening and closing tags.

Assisted-by: Claude-Opus-4-6

---
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: passed
  - task: lint_repl_help
    status: na
  - task: lint_javascript_src
    status: passed
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: passed
  - 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
---
---
 .../remark/plugins/remark-includes/README.md  | 136 +++++++++++++++++
 .../remark-includes/examples/fixtures/bar.txt |   3 +
 .../remark-includes/examples/fixtures/foo.txt |   3 +
 .../examples/fixtures/simple.txt              |   9 ++
 .../plugins/remark-includes/examples/index.js |  39 +++++
 .../plugins/remark-includes/lib/attacher.js   |  71 +++++++++
 .../plugins/remark-includes/lib/defaults.json |   3 +
 .../plugins/remark-includes/lib/index.js      |  40 +++++
 .../remark-includes/lib/transformer.js        | 141 ++++++++++++++++++
 .../plugins/remark-includes/package.json      |  53 +++++++
 10 files changed, 498 insertions(+)
 create mode 100644 lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/README.md
 create mode 100644 lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/fixtures/bar.txt
 create mode 100644 lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/fixtures/foo.txt
 create mode 100644 lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/fixtures/simple.txt
 create mode 100644 lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/index.js
 create mode 100644 lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/attacher.js
 create mode 100644 lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/defaults.json
 create mode 100644 lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/index.js
 create mode 100644 lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js
 create mode 100644 lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/package.json

diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/README.md b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/README.md
new file mode 100644
index 000000000000..7b9a4da0649c
--- /dev/null
+++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/README.md
@@ -0,0 +1,136 @@
+<!--
+
+@license Apache-2.0
+
+Copyright (c) 2026 The Stdlib Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+-->
+
+# Includes
+
+> [remark][remark] plugin to insert content from external Markdown files.
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var includes = require( '@stdlib/_tools/remark/plugins/remark-includes' );
+```
+
+#### includes( \[options\] )
+
+Attaches a plugin to a [remark][remark] processor in order to insert content from external Markdown files between include comment directives.
+
+<!-- eslint-disable node/no-sync -->
+
+```javascript
+var remark = require( 'remark' );
+
+var str = '# Hello World!\n';
+str += '\n';
+str += '<!-- <include path="./docs/snippets/foo.md"> -->\n';
+str += '\n';
+str += '<!-- </include> -->\n';
+
+var vfile = remark().use( includes ).processSync( str );
+```
+
+The plugin recognizes HTML comments of the form
+
+```html
+<!-- <include path="./relative/path/to/file.md"> -->
+
+<!-- </include> -->
+```
+
+and inserts the parsed Markdown content of the referenced file between the opening and closing comment tags.
+
+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.
+
+</section>
+
+<!-- /.usage -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error", node/no-sync: "off" -->
+
+```javascript
+var join = require( 'path' ).join;
+var readFileSync = require( 'fs' ).readFileSync;
+var remark = require( 'remark' );
+var includes = require( '@stdlib/_tools/remark/plugins/remark-includes' );
+
+// Load a Markdown file...
+var fpath = join( __dirname, 'fixtures', 'simple.txt' );
+var opts = {
+    'encoding': 'utf8'
+};
+var file = readFileSync( fpath, opts );
+
+// Insert includes:
+var vfile = remark().use( includes, {
+    'dir': join( __dirname, 'fixtures' )
+}).processSync( file );
+
+console.log( vfile.contents );
+```
+
+</section>
+
+<!-- /.examples -->
+
+<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
+
+<section class="related">
+
+</section>
+
+<!-- /.related -->
+
+<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="links">
+
+[remark]: https://github.com/wooorm/remark
+
+</section>
+
+<!-- /.links -->
diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/fixtures/bar.txt b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/fixtures/bar.txt
new file mode 100644
index 000000000000..c5c6767b8c84
--- /dev/null
+++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/fixtures/bar.txt
@@ -0,0 +1,3 @@
+## Bap
+
+Bip bop.
diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/fixtures/foo.txt b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/fixtures/foo.txt
new file mode 100644
index 000000000000..5789d7360945
--- /dev/null
+++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/fixtures/foo.txt
@@ -0,0 +1,3 @@
+## Greeting
+
+Beep boop.
diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/fixtures/simple.txt b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/fixtures/simple.txt
new file mode 100644
index 000000000000..a119237d09c3
--- /dev/null
+++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/fixtures/simple.txt
@@ -0,0 +1,9 @@
+# Hello World!
+
+<!-- <include path="./foo.txt"> -->
+
+<!-- </include> -->
+
+<!-- <include path="./bar.txt"> -->
+
+<!-- </include> -->
diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/index.js b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/index.js
new file mode 100644
index 000000000000..724df5d4c06c
--- /dev/null
+++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/index.js
@@ -0,0 +1,39 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2026 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+var readFileSync = require( 'fs' ).readFileSync;
+var join = require( 'path' ).join;
+var remark = require( 'remark' );
+var includes = require( './../lib' );
+
+// Load a Markdown file...
+var fpath = join( __dirname, 'fixtures', 'simple.txt' );
+var opts = {
+	'encoding': 'utf8'
+};
+var file = readFileSync( fpath, opts );
+
+// Insert includes:
+var vfile = remark().use( includes, {
+	'dir': join( __dirname, 'fixtures' )
+}).processSync( file );
+
+// Print the results:
+console.log( vfile.contents );
diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/attacher.js b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/attacher.js
new file mode 100644
index 000000000000..d9edc6482749
--- /dev/null
+++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/attacher.js
@@ -0,0 +1,71 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2026 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MODULES //
+
+var logger = require( 'debug' );
+var copy = require( '@stdlib/utils/copy' );
+var isObject = require( '@stdlib/assert/is-plain-object' );
+var hasOwnProp = require( '@stdlib/assert/has-own-property' );
+var isString = require( '@stdlib/assert/is-string' ).isPrimitive;
+var format = require( '@stdlib/string/format' );
+var transformerFactory = require( './transformer.js' );
+var defaults = require( './defaults.json' );
+
+
+// VARIABLES //
+
+var debug = logger( 'remark-includes:attacher' );
+
+
+// MAIN //
+
+/**
+* Attaches a plugin to a remark processor in order to insert content from external Markdown files.
+*
+* @param {Options} [options] - options object
+* @param {string} [options.dir] - base directory for resolving include paths
+* @throws {TypeError} options argument must be an object
+* @throws {TypeError} must provide valid options
+* @returns {Function} transformer
+*/
+function attacher( options ) {
+	var opts = copy( defaults );
+
+	// NOTE: cannot use `arguments.length` check, as `options` may be explicitly passed as `undefined`
+	if ( options !== void 0 ) {
+		if ( !isObject( options ) ) {
+			throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );
+		}
+		if ( hasOwnProp( options, 'dir' ) ) {
+			if ( !isString( options.dir ) ) {
+				throw new TypeError( format( 'invalid option. `%s` option must be a string. Option: `%s`.', 'dir', options.dir ) );
+			}
+			opts.dir = options.dir;
+		}
+	}
+	debug( 'Attaching a plugin configured with the following options: %s', JSON.stringify( opts ) );
+	return transformerFactory( opts );
+}
+
+
+// EXPORTS //
+
+module.exports = attacher;
diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/defaults.json b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/defaults.json
new file mode 100644
index 000000000000..94c89fb03e28
--- /dev/null
+++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/defaults.json
@@ -0,0 +1,3 @@
+{
+  "dir": null
+}
diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/index.js b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/index.js
new file mode 100644
index 000000000000..a91ac111e745
--- /dev/null
+++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/index.js
@@ -0,0 +1,40 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2026 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+/**
+* remark plugin to insert content from external Markdown files.
+*
+* @module @stdlib/_tools/remark/plugins/remark-includes
+*
+* @example
+* var remark = require( 'remark' );
+* var includes = require( '@stdlib/_tools/remark/plugins/remark-includes' );
+*
+* var transform = remark().use( includes ).processSync;
+*/
+
+// MODULES //
+
+var main = require( './attacher.js' );
+
+
+// EXPORTS //
+
+module.exports = main;
diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js
new file mode 100644
index 000000000000..90d91586d107
--- /dev/null
+++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js
@@ -0,0 +1,141 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2026 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MODULES //
+
+var resolve = require( 'path' ).resolve;
+var logger = require( 'debug' );
+var remark = require( 'remark' );
+var visit = require( 'unist-util-visit' );
+var readFileSync = require( '@stdlib/fs/read-file' ).sync;
+var format = require( '@stdlib/string/format' );
+
+
+// VARIABLES //
+
+var debug = logger( 'remark-includes:transformer' );
+var INCLUDE_START = /<!--\s*<include\s+path="([^"]*)">\s*-->/;
+var INCLUDE_END = /<!--\s*<\/include>\s*-->/;
+
+
+// MAIN //
+
+/**
+* Returns a transformer function.
+*
+* @private
+* @param {Options} opts - transformer options
+* @param {(string|null)} opts.dir - base directory for resolving include paths
+* @returns {Function} transformer function
+*/
+function factory( opts ) {
+	return transformer;
+
+	/**
+	* Transforms a Markdown abstract syntax tree (AST) by inserting content from external files.
+	*
+	* @private
+	* @param {Node} tree - root node of the AST
+	* @param {File} file - virtual file
+	*/
+	function transformer( tree, file ) {
+		debug( 'Processing virtual file: %s', file.path );
+		visit( tree, 'html', visitor );
+		debug( 'Finished processing virtual file.' );
+
+		/**
+		* Callback invoked upon finding an HTML node.
+		*
+		* @private
+		* @param {Node} node - AST node
+		* @param {number} index - position of `node` in `parent`
+		* @param {Node} parent - parent of `node`
+		*/
+		function visitor( node, index, parent ) {
+			var children;
+			var content;
+			var fpath;
+			var match;
+			var base;
+			var end;
+			var i;
+
+			match = INCLUDE_START.exec( node.value );
+			if ( match === null ) {
+				return;
+			}
+			debug( 'Found an include directive: %s', match[ 1 ] );
+
+			// Resolve the file path:
+			if ( opts.dir ) {
+				base = opts.dir;
+			} else {
+				base = file.dirname;
+			}
+			fpath = resolve( base, match[ 1 ] );
+			debug( 'Resolved include path: %s', fpath );
+
+			// Read the file:
+			content = readFileSync( fpath, {
+				'encoding': 'utf8'
+			});
+			if ( content instanceof Error ) {
+				debug( 'Unable to resolve include: %s. Error: %s', fpath, content.message );
+				file.message( format( 'unable to resolve include: %s', fpath ), node );
+				return;
+			}
+			debug( 'Successfully read include file.' );
+
+			// Find the matching closing tag by scanning subsequent siblings:
+			end = -1;
+			for ( i = index + 1; i < parent.children.length; i++ ) {
+				if (
+					parent.children[ i ].type === 'html' &&
+					INCLUDE_END.test( parent.children[ i ].value )
+				) {
+					end = i;
+					break;
+				}
+			}
+			if ( end === -1 ) {
+				debug( 'Missing closing include comment for: %s', match[ 1 ] );
+				file.message( format( 'missing closing include comment for: %s', match[ 1 ] ), node );
+				return;
+			}
+			debug( 'Found closing include comment at index: %d', end );
+
+			// Parse the included Markdown content into AST nodes:
+			children = remark().parse( content ).children;
+			debug( 'Parsed %d nodes from include file.', children.length );
+
+			// Remove existing nodes between the opening and closing tags:
+			parent.children.splice( index + 1, end - index - 1 );
+
+			// Insert the parsed nodes between the opening and closing tags:
+			Array.prototype.splice.apply(parent.children, [ index + 1, 0 ].concat( children ));
+			debug( 'Inserted include content.' );
+		}
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = factory;
diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/package.json b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/package.json
new file mode 100644
index 000000000000..ad14424793db
--- /dev/null
+++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/package.json
@@ -0,0 +1,53 @@
+{
+  "name": "@stdlib/_tools/remark/plugins/remark-includes",
+  "version": "0.0.0",
+  "description": "remark plugin to insert content from external Markdown files.",
+  "license": "Apache-2.0",
+  "author": {
+    "name": "The Stdlib Authors",
+    "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+  },
+  "contributors": [
+    {
+      "name": "The Stdlib Authors",
+      "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+    }
+  ],
+  "main": "./lib",
+  "directories": {
+    "example": "./examples",
+    "lib": "./lib"
+  },
+  "scripts": {},
+  "homepage": "https://github.com/stdlib-js/stdlib",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/stdlib-js/stdlib.git"
+  },
+  "bugs": {
+    "url": "https://github.com/stdlib-js/stdlib/issues"
+  },
+  "dependencies": {},
+  "devDependencies": {},
+  "engines": {
+    "node": ">=6.0.0",
+    "npm": ">2.7.0"
+  },
+  "keywords": [
+    "tools",
+    "markdown",
+    "md",
+    "mdown",
+    "html",
+    "include",
+    "includes",
+    "insert",
+    "snippet",
+    "snippets",
+    "external",
+    "file",
+    "remark",
+    "mdast",
+    "plugin"
+  ]
+}

From 85f141abc0c49105e9e25dd1aa76ccdb3107692f Mon Sep 17 00:00:00 2001
From: Mara Averick <maraaverick@gmail.com>
Date: Thu, 2 Apr 2026 07:37:57 -0600
Subject: [PATCH 2/9] feat(make): add rules for resolving Markdown includes

Add `markdown-includes` and `markdown-includes-files` rules to process Markdown files using the `remark-includes` plugin, enabling the automated insertion of content from external files.

---
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: na
  - 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
---
---
 tools/make/lib/markdown/Makefile    |  1 +
 tools/make/lib/markdown/includes.mk | 99 +++++++++++++++++++++++++++++
 2 files changed, 100 insertions(+)
 create mode 100644 tools/make/lib/markdown/includes.mk

diff --git a/tools/make/lib/markdown/Makefile b/tools/make/lib/markdown/Makefile
index 258f2ce346d7..3f3096b55c9b 100644
--- a/tools/make/lib/markdown/Makefile
+++ b/tools/make/lib/markdown/Makefile
@@ -21,6 +21,7 @@
 # Note: keep in alphabetical order...
 include $(TOOLS_MAKE_LIB_DIR)/markdown/assets.mk
 include $(TOOLS_MAKE_LIB_DIR)/markdown/equations.mk
+include $(TOOLS_MAKE_LIB_DIR)/markdown/includes.mk
 include $(TOOLS_MAKE_LIB_DIR)/markdown/namespace_toc.mk
 include $(TOOLS_MAKE_LIB_DIR)/markdown/pkg_urls.mk
 include $(TOOLS_MAKE_LIB_DIR)/markdown/related.mk
diff --git a/tools/make/lib/markdown/includes.mk b/tools/make/lib/markdown/includes.mk
new file mode 100644
index 000000000000..6b9419e47ded
--- /dev/null
+++ b/tools/make/lib/markdown/includes.mk
@@ -0,0 +1,99 @@
+#/
+# @license Apache-2.0
+#
+# Copyright (c) 2026 The Stdlib Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#/
+
+# VARIABLES #
+
+# Define the path to the remark configuration file:
+REMARK_INCLUDES_CONF ?= $(CONFIG_DIR)/remark/.remarkrc.js
+
+# Define the path to the remark ignore file:
+REMARK_INCLUDES_IGNORE ?= $(ROOT_DIR)/.remarkignore
+
+# Define the path to a plugin which inserts content from external Markdown files:
+REMARK_INCLUDES_PLUGIN ?= $(TOOLS_PKGS_DIR)/remark/plugins/remark-includes
+REMARK_INCLUDES_PLUGIN_SETTINGS ?=
+REMARK_INCLUDES_PLUGIN_FLAGS ?= --use $(REMARK_INCLUDES_PLUGIN)=$(REMARK_INCLUDES_PLUGIN_SETTINGS)
+
+# Define command-line options when invoking the remark executable:
+REMARK_INCLUDES_FLAGS ?= \
+	--ext $(MARKDOWN_FILENAME_EXT) \
+	--rc-path $(REMARK_INCLUDES_CONF) \
+	--ignore-path $(REMARK_INCLUDES_IGNORE)
+
+# Define the remark output option:
+REMARK_INCLUDES_OUTPUT_FLAG ?= --output
+
+
+# RULES #
+
+#/
+# Resolves Markdown include directives by inserting content from external Markdown files.
+#
+# ## Notes
+#
+# -   This rule is useful when wanting to glob for Markdown files (e.g., process all Markdown files for a particular package).
+# -   In order to resolve includes, a Markdown file must contain include comment directives.
+# -   This recipe should be run before other Markdown processing recipes (e.g., equations) since included content may contain additional directives.
+#
+# @param {string} [MARKDOWN_FILTER] - file path pattern (e.g., `.*/math/base/special/.*`)
+# @param {string} [MARKDOWN_PATTERN] - filename pattern (e.g., `*.md`)
+#
+# @example
+# make markdown-includes
+#
+# @example
+# make markdown-includes MARKDOWN_PATTERN='README.md' MARKDOWN_FILTER='.*/math/base/special/.*'
+#/
+markdown-includes: $(NODE_MODULES)
+	$(QUIET) $(FIND_MARKDOWN_CMD) | grep '^[\/]\|^[a-zA-Z]:[/\]' | while read -r file; do \
+		echo ""; \
+		echo "Processing file: $$file"; \
+		"$(REMARK)" \
+			$$file \
+			$(REMARK_INCLUDES_FLAGS) \
+			$(REMARK_INCLUDES_PLUGIN_FLAGS) \
+			$(REMARK_INCLUDES_OUTPUT_FLAG) || exit 1; \
+	done
+
+.PHONY: markdown-includes
+
+#/
+# Resolves Markdown include directives for a specified list of files.
+#
+# ## Notes
+#
+# -   This rule is useful when wanting to process a list of Markdown files generated by some other command (e.g., a list of changed Markdown files obtained via `git diff`).
+# -   In order to resolve includes, a Markdown file must contain include comment directives.
+#
+# @param {string} FILES - list of files
+#
+# @example
+# make markdown-includes-files FILES='/foo/foo.md /foo/bar.md'
+#/
+markdown-includes-files: $(NODE_MODULES)
+	$(QUIET) for file in $(FILES); do \
+		echo ""; \
+		echo "Processing file: $$file"; \
+		"$(REMARK)" \
+			$$file \
+			$(REMARK_INCLUDES_FLAGS) \
+			$(REMARK_INCLUDES_PLUGIN_FLAGS) \
+			$(REMARK_INCLUDES_OUTPUT_FLAG) || exit 1; \
+	done
+
+.PHONY: markdown-includes-files

From 923ed959fc5f13bb1ed61654609a5210b492e514 Mon Sep 17 00:00:00 2001
From: Mara Averick <maraaverick@gmail.com>
Date: Thu, 2 Apr 2026 08:48:14 -0600
Subject: [PATCH 3/9] fix(remark-includes): add base-path guard

Add a check to verify that a base directory is available before attempting to resolve an include path and report an error if resolution is not possible.

Assisted-by: Codex-GPT-5-4
---
 .../remark/plugins/remark-includes/lib/transformer.js       | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js
index 90d91586d107..efda2262d908 100644
--- a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js
+++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js
@@ -84,11 +84,15 @@ function factory( opts ) {
 			debug( 'Found an include directive: %s', match[ 1 ] );
 
 			// Resolve the file path:
-			if ( opts.dir ) {
+			if ( opts.dir !== null ) {
 				base = opts.dir;
 			} else {
 				base = file.dirname;
 			}
+			if ( base === void 0 || base === null ) {
+				debug( 'Missing base directory for include path: %s', match[ 1 ] );
+				file.message( format( 'unable to resolve include path due to missing base directory: %s', match[ 1 ] ), node );
+				return;
 			fpath = resolve( base, match[ 1 ] );
 			debug( 'Resolved include path: %s', fpath );
 

From aad1f6f348811603d9e047b1ac58289ede4d4473 Mon Sep 17 00:00:00 2001
From: Mara Averick <maraaverick@gmail.com>
Date: Thu, 2 Apr 2026 08:50:04 -0600
Subject: [PATCH 4/9] fix(remark-includes): use active parser context for
 includes

Stores the current processor via this and parses include content with processor.parse, keeping parsing behavior aligned with the main remark pipeline.

Assisted-by: GPT-5-4
---
 .../plugins/remark-includes/lib/transformer.js     | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js
index efda2262d908..a64fb781d17a 100644
--- a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js
+++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js
@@ -22,7 +22,6 @@
 
 var resolve = require( 'path' ).resolve;
 var logger = require( 'debug' );
-var remark = require( 'remark' );
 var visit = require( 'unist-util-visit' );
 var readFileSync = require( '@stdlib/fs/read-file' ).sync;
 var format = require( '@stdlib/string/format' );
@@ -56,6 +55,9 @@ function factory( opts ) {
 	* @param {File} file - virtual file
 	*/
 	function transformer( tree, file ) {
+		var processor;
+
+		processor = this;
 		debug( 'Processing virtual file: %s', file.path );
 		visit( tree, 'html', visitor );
 		debug( 'Finished processing virtual file.' );
@@ -93,6 +95,7 @@ function factory( opts ) {
 				debug( 'Missing base directory for include path: %s', match[ 1 ] );
 				file.message( format( 'unable to resolve include path due to missing base directory: %s', match[ 1 ] ), node );
 				return;
+			}
 			fpath = resolve( base, match[ 1 ] );
 			debug( 'Resolved include path: %s', fpath );
 
@@ -126,14 +129,19 @@ function factory( opts ) {
 			debug( 'Found closing include comment at index: %d', end );
 
 			// Parse the included Markdown content into AST nodes:
-			children = remark().parse( content ).children;
+			if ( processor && typeof processor.parse === 'function' ) {
+				children = processor.parse( content ).children;
+			} else {
+				file.message( format( 'unable to parse include using processor context: %s', fpath ), node );
+				return;
+			}
 			debug( 'Parsed %d nodes from include file.', children.length );
 
 			// Remove existing nodes between the opening and closing tags:
 			parent.children.splice( index + 1, end - index - 1 );
 
 			// Insert the parsed nodes between the opening and closing tags:
-			Array.prototype.splice.apply(parent.children, [ index + 1, 0 ].concat( children ));
+			Array.prototype.splice.apply( parent.children, [ index + 1, 0 ].concat( children ) );
 			debug( 'Inserted include content.' );
 		}
 	}

From 66c4997b84d50e00dd147b8af06c2982cf1de90b Mon Sep 17 00:00:00 2001
From: Mara Averick <maraaverick@gmail.com>
Date: Thu, 2 Apr 2026 09:04:12 -0600
Subject: [PATCH 5/9] fix(remark-includes): resolve lint errors in attacher and
 transformer

Capture the remark processor context in the attacher via `this` and
pass it to the transformer factory, avoiding `consistent-this` and
`no-invalid-this` violations. Flip negated condition to satisfy
`no-negated-condition` and wrap long line for `max-len` compliance.

Assisted-by: Claude Opus 4.6 <noreply@anthropic.com>

---
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: na
  - task: lint_package_json
    status: na
  - task: lint_repl_help
    status: na
  - task: lint_javascript_src
    status: passed
  - 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
---
---
 .../remark/plugins/remark-includes/lib/attacher.js |  2 +-
 .../plugins/remark-includes/lib/transformer.js     | 14 ++++++--------
 2 files changed, 7 insertions(+), 9 deletions(-)

diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/attacher.js b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/attacher.js
index d9edc6482749..e6c215a32dce 100644
--- a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/attacher.js
+++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/attacher.js
@@ -62,7 +62,7 @@ function attacher( options ) {
 		}
 	}
 	debug( 'Attaching a plugin configured with the following options: %s', JSON.stringify( opts ) );
-	return transformerFactory( opts );
+	return transformerFactory( opts, this ); // eslint-disable-line no-invalid-this
 }
 
 
diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js
index a64fb781d17a..1ad2ac0e500e 100644
--- a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js
+++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js
@@ -42,9 +42,10 @@ var INCLUDE_END = /<!--\s*<\/include>\s*-->/;
 * @private
 * @param {Options} opts - transformer options
 * @param {(string|null)} opts.dir - base directory for resolving include paths
+* @param {Object} processor - remark processor instance
 * @returns {Function} transformer function
 */
-function factory( opts ) {
+function factory( opts, processor ) {
 	return transformer;
 
 	/**
@@ -55,9 +56,6 @@ function factory( opts ) {
 	* @param {File} file - virtual file
 	*/
 	function transformer( tree, file ) {
-		var processor;
-
-		processor = this;
 		debug( 'Processing virtual file: %s', file.path );
 		visit( tree, 'html', visitor );
 		debug( 'Finished processing virtual file.' );
@@ -86,10 +84,10 @@ function factory( opts ) {
 			debug( 'Found an include directive: %s', match[ 1 ] );
 
 			// Resolve the file path:
-			if ( opts.dir !== null ) {
-				base = opts.dir;
-			} else {
+			if ( opts.dir === null ) {
 				base = file.dirname;
+			} else {
+				base = opts.dir;
 			}
 			if ( base === void 0 || base === null ) {
 				debug( 'Missing base directory for include path: %s', match[ 1 ] );
@@ -141,7 +139,7 @@ function factory( opts ) {
 			parent.children.splice( index + 1, end - index - 1 );
 
 			// Insert the parsed nodes between the opening and closing tags:
-			Array.prototype.splice.apply( parent.children, [ index + 1, 0 ].concat( children ) );
+			Array.prototype.splice.apply(parent.children, [ index + 1, 0 ].concat( children ));
 			debug( 'Inserted include content.' );
 		}
 	}

From f4b98dd48ae35343f79522b785b4fa387191d52a Mon Sep 17 00:00:00 2001
From: Mara Averick <maraaverick@gmail.com>
Date: Thu, 2 Apr 2026 09:25:25 -0600
Subject: [PATCH 6/9] fix(remark-includes): correct fixtures filepath for
 README

---
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
---
---
 .../@stdlib/_tools/remark/plugins/remark-includes/README.md   | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/README.md b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/README.md
index 7b9a4da0649c..a5f4d9c9bb21 100644
--- a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/README.md
+++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/README.md
@@ -99,7 +99,7 @@ var remark = require( 'remark' );
 var includes = require( '@stdlib/_tools/remark/plugins/remark-includes' );
 
 // Load a Markdown file...
-var fpath = join( __dirname, 'fixtures', 'simple.txt' );
+var fpath = join( __dirname, 'examples', 'fixtures', 'simple.txt' );
 var opts = {
     'encoding': 'utf8'
 };
@@ -107,7 +107,7 @@ var file = readFileSync( fpath, opts );
 
 // Insert includes:
 var vfile = remark().use( includes, {
-    'dir': join( __dirname, 'fixtures' )
+    'dir': join( __dirname, 'examples', 'fixtures' )
 }).processSync( file );
 
 console.log( vfile.contents );

From 88912e5f54c3368439b3b393e59dafd9489d285a Mon Sep 17 00:00:00 2001
From: Mara Averick <maraaverick@gmail.com>
Date: Thu, 2 Apr 2026 10:10:44 -0600
Subject: [PATCH 7/9] 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
---
---
 .../remark/plugins/remark-includes/README.md  | 33 ++++++++-----------
 1 file changed, 13 insertions(+), 20 deletions(-)

diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/README.md b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/README.md
index a5f4d9c9bb21..b2d2baecf18c 100644
--- a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/README.md
+++ b/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 -->

From 2f173126c57f43054daf9268fafac2703e00b089 Mon Sep 17 00:00:00 2001
From: Mara Averick <maraaverick@gmail.com>
Date: Thu, 9 Apr 2026 07:57:29 -0600
Subject: [PATCH 8/9] fix(remark-includes): address review feedback

Create a local remark parser in the transformer and use it to parse
included markdown content. This removes reliance on processor context
being forwarded through the attacher, which improves robustness.

Update docs and examples to use the fs/read-file sync helper and
document that include blocks must be non-overlapping sibling regions.

Assisted-by: Claude-Sonnet-4-6

---
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: passed
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: passed
  - 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
---
---
 .../remark/plugins/remark-includes/README.md     |  4 +++-
 .../plugins/remark-includes/examples/index.js    |  2 +-
 .../plugins/remark-includes/lib/attacher.js      |  2 +-
 .../plugins/remark-includes/lib/transformer.js   | 16 +++++++---------
 4 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/README.md b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/README.md
index b2d2baecf18c..2b8bd1a4d9be 100644
--- a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/README.md
+++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/README.md
@@ -67,6 +67,8 @@ and inserts the parsed Markdown content of the referenced file between the openi
 
 The opening include directive requires a `path` attribute with a double-quoted value.
 
+Include blocks must be non-overlapping sibling regions. Nested or overlapping include blocks are not supported.
+
 The plugin accepts the following `options`:
 
 -   **dir**: base directory for resolving include paths. Default: `null` (resolved relative to the processed file's directory).
@@ -87,8 +89,8 @@ If an opening include directive does not have a matching closing include directi
 
 ```javascript
 var join = require( 'path' ).join;
-var readFileSync = require( 'fs' ).readFileSync;
 var remark = require( 'remark' );
+var readFileSync = require( '@stdlib/fs/read-file' ).sync;
 var includes = require( '@stdlib/_tools/remark/plugins/remark-includes' );
 
 // Load a Markdown file...
diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/index.js b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/index.js
index 724df5d4c06c..a1a1cd7e4891 100644
--- a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/index.js
+++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/index.js
@@ -18,9 +18,9 @@
 
 'use strict';
 
-var readFileSync = require( 'fs' ).readFileSync;
 var join = require( 'path' ).join;
 var remark = require( 'remark' );
+var readFileSync = require( '@stdlib/fs/read-file' ).sync;
 var includes = require( './../lib' );
 
 // Load a Markdown file...
diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/attacher.js b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/attacher.js
index e6c215a32dce..d9edc6482749 100644
--- a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/attacher.js
+++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/attacher.js
@@ -62,7 +62,7 @@ function attacher( options ) {
 		}
 	}
 	debug( 'Attaching a plugin configured with the following options: %s', JSON.stringify( opts ) );
-	return transformerFactory( opts, this ); // eslint-disable-line no-invalid-this
+	return transformerFactory( opts );
 }
 
 
diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js
index 1ad2ac0e500e..8359710143b5 100644
--- a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js
+++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js
@@ -21,6 +21,7 @@
 // MODULES //
 
 var resolve = require( 'path' ).resolve;
+var remark = require( 'remark' );
 var logger = require( 'debug' );
 var visit = require( 'unist-util-visit' );
 var readFileSync = require( '@stdlib/fs/read-file' ).sync;
@@ -42,10 +43,12 @@ var INCLUDE_END = /<!--\s*<\/include>\s*-->/;
 * @private
 * @param {Options} opts - transformer options
 * @param {(string|null)} opts.dir - base directory for resolving include paths
-* @param {Object} processor - remark processor instance
 * @returns {Function} transformer function
 */
-function factory( opts, processor ) {
+function factory( opts ) {
+	var parser;
+
+	parser = remark();
 	return transformer;
 
 	/**
@@ -127,19 +130,14 @@ function factory( opts, processor ) {
 			debug( 'Found closing include comment at index: %d', end );
 
 			// Parse the included Markdown content into AST nodes:
-			if ( processor && typeof processor.parse === 'function' ) {
-				children = processor.parse( content ).children;
-			} else {
-				file.message( format( 'unable to parse include using processor context: %s', fpath ), node );
-				return;
-			}
+			children = parser.parse( content ).children;
 			debug( 'Parsed %d nodes from include file.', children.length );
 
 			// Remove existing nodes between the opening and closing tags:
 			parent.children.splice( index + 1, end - index - 1 );
 
 			// Insert the parsed nodes between the opening and closing tags:
-			Array.prototype.splice.apply(parent.children, [ index + 1, 0 ].concat( children ));
+			Array.prototype.splice.apply( parent.children, [ index + 1, 0 ].concat( children ) ); // eslint-disable-line max-len
 			debug( 'Inserted include content.' );
 		}
 	}

From a52b36ee8bea76b7cf351df087896a7862c788be Mon Sep 17 00:00:00 2001
From: Mara Averick <maraaverick@gmail.com>
Date: Wed, 15 Apr 2026 07:19:42 -0600
Subject: [PATCH 9/9] refactor(remark): align splice idiom with sibling plugins

Alias `parent.children` as `c` immediately before the `splice.apply`
call and invoke through `c.splice.apply( c, ... )`.

Assisted-by: Claude Opus 4.6 <noreply@anthropic.com>

---
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: na
  - task: lint_package_json
    status: na
  - task: lint_repl_help
    status: na
  - task: lint_javascript_src
    status: passed
  - 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
---
---
 .../_tools/remark/plugins/remark-includes/lib/transformer.js  | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js
index 8359710143b5..0e210fd1e329 100644
--- a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js
+++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/transformer.js
@@ -78,6 +78,7 @@ function factory( opts ) {
 			var match;
 			var base;
 			var end;
+			var c;
 			var i;
 
 			match = INCLUDE_START.exec( node.value );
@@ -137,7 +138,8 @@ function factory( opts ) {
 			parent.children.splice( index + 1, end - index - 1 );
 
 			// Insert the parsed nodes between the opening and closing tags:
-			Array.prototype.splice.apply( parent.children, [ index + 1, 0 ].concat( children ) ); // eslint-disable-line max-len
+			c = parent.children;
+			c.splice.apply( c, [ index + 1, 0 ].concat( children ) );
 			debug( 'Inserted include content.' );
 		}
 	}