feat: add _tools/remark/plugins/remark-img-figures

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

@@ -0,0 +1,114 @@
+<!--
+
+@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.
+
+-->
+
+# Image Figures
+
+> [remark][remark] plugin to insert Markdown image figure elements.
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var insertFigures = require( '@stdlib/_tools/remark/plugins/remark-img-figures' );
+```
+
+#### insertFigures()
+
+Attaches a plugin to a [remark][remark] processor in order to insert Markdown image figure elements between figure comments.
+
+<!-- eslint-disable no-useless-escape, no-sync, n/no-sync -->
+
+```javascript
+var remark = require( 'remark' );
+
+var str = 'Padding around chart area:';
+str += '\n';
+str += '<!-- <figure class="figure" align="center" label="fig:padding" src="./docs/img/fig_padding.svg" alt="Padding diagram"> -->\n';
+str += '\n';
+str += '<!-- </figure> -->';
+
+var vfile = remark().use( insertFigures ).processSync( str );
+
+console.log( vfile.contents );
+/* =>
+    Padding around chart area:
+
+    <!-- <figure class="figure" align="center" label="fig:padding" src="./docs/img/fig_padding.svg" alt="Padding diagram"> -->
+
+    <div class="figure" align="center" data-figure="fig:padding">
+        <img src="./docs/img/fig_padding.svg" alt="Padding diagram">
+        <br>
+    </div>
+
+    <!-- </figure> -->
+*/
+```
+
+</section>
+
+<!-- /.usage -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint-disable no-sync, n/no-sync -->
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var join = require( 'path' ).join;
+var remark = require( 'remark' );
+var readFileSync = require( '@stdlib/fs/read-file' ).sync;
+var insertFigures = require( '@stdlib/_tools/remark/plugins/remark-img-figures' );
+
+// Load a Markdown file...
+var fpath = join( __dirname, 'fixtures/simple.txt' );
+var opts = {
+    'encoding': 'utf8'
+};
+var file = readFileSync( fpath, opts );
+
+// Insert figures:
+var out = remark().use( insertFigures ).processSync( file );
+```
+
+</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 -->

lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/examples/fixtures/simple.txt

@@ -0,0 +1,18 @@
+# Padding
+
+<section class="intro">
+
+Padding around chart area:
+
+<!-- <figure class="figure" align="center" label="fig:padding" src="./docs/img/fig_padding.svg" alt="Padding diagram"> -->
+
+<div class="figure" align="center" data-figure="fig:padding">
+    <img src="./docs/img/fig_padding.svg" alt="Padding diagram">
+    <br>
+</div>
+
+<!-- </figure> -->
+
+</section>
+
+<!-- /.intro -->

lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/examples/index.js

@@ -0,0 +1,37 @@
+/**
+* @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 insertFigures = require( './../lib' );
+
+// Load a Markdown file...
+var fpath = join( __dirname, 'fixtures/simple.txt' );
+var opts = {
+	'encoding': 'utf8'
+};
+var file = readFileSync( fpath, opts );
+
+// Insert figures:
+var out = remark().use( insertFigures ).processSync( file );
+
+// Print the results:
+console.log( out.contents );

lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/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 image figure elements into Markdown documents.
+*
+* @module @stdlib/_tools/remark/plugins/remark-img-figures
+*
+* @example
+* var remark = require( 'remark' );
+* var insertFigures = require( '@stdlib/_tools/remark/plugins/remark-img-figures' );
+*
+* var transform = remark().use( insertFigures ).processSync;
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;

lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/lib/insert_figures.js

@@ -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.
+*/
+
+'use strict';
+
+// MODULES //
+
+var logger = require( 'debug' );
+var createElement = require( '@stdlib/_tools/markdown/img-svg-figure' );
+var format = require( '@stdlib/string/format' );
+
+
+// VARIABLES //
+
+var debug = logger( 'remark-img-figures:insert_figures' );
+var FIG_START = /<!-- <figure.*> -->/;
+var FIG_END = /<!-- <\/figure> -->/;
+var LABEL = /label="([^"]*)"/;
+var ALT = /alt="([^"]*)"/;
+var SRC = /src="([^"]*)"/;
+var ALIGN = /align="([^"]*)"/;
+var CLASS = /class="([^"]*)"/;
+
+
+// MAIN //
+
+/**
+* Inserts a figure image element into a Markdown AST.
+*
+* @private
+* @param {Node} node - reference node
+* @param {number} index - position of `node` in `parent`
+* @param {Node} parent - parent of `node`
+* @throws {Error} figure comments must have a valid label
+* @throws {Error} figure comments must have valid alternate text
+* @throws {Error} figure comments must have a valid source path
+* @throws {Error} figure comments must have starting and ending comments
+*/
+function insertFigures( node, index, parent ) {
+	var divNode;
+	var label;
+	var align;
+	var html;
+	var opts;
+	var cls;
+	var alt;
+	var src;
+
+	if ( FIG_START.test( node.value ) === true ) {
+		debug( 'Found a figure...' );
+
+		label = LABEL.exec( node.value );
+		if ( label === null ) {
+			debug( 'Invalid node: %s', node.value );
+			throw new Error( format( 'invalid node. Figure comments must have a valid label. Node: `%s`.', node.value ) );
+		}
+		label = label[ 1 ];
+		debug( 'Label: %s', label );
+
+		alt = ALT.exec( node.value );
+		if ( alt === null ) {
+			debug( 'Invalid node: %s', node.value );
+			throw new Error( format( 'invalid node. Figure comments must have valid alternate text. Node: `%s`.', node.value ) );
+		}
+		alt = alt[ 1 ];
+		debug( 'Alternate text: %s', alt );
+
+		src = SRC.exec( node.value );
+		if ( src === null ) {
+			debug( 'Invalid node: %s', node.value );
+			throw new Error( format( 'invalid node. Figure comments must have a valid source path. Node: `%s`.', node.value ) );
+		}
+		src = src[ 1 ];
+		debug( 'Source: %s', src );
+
+		align = ALIGN.exec( node.value );
+		align = ( align ) ? align[ 1 ] : 'center';
+		debug( 'Alignment: %s', align );
+
+		cls = CLASS.exec( node.value );
+		cls = ( cls ) ? cls[ 1 ] : 'figure';
+		debug( 'Class: %s', cls );
+
+		opts = {
+			'className': cls,
+			'align': align,
+			'label': label,
+			'src': src,
+			'alt': alt
+		};
+		html = createElement( opts );
+		debug( 'Generated HTML: %s', html );
+
+		divNode = {
+			'type': 'html',
+			'value': html
+		};
+
+		// Case 1: insert new node between figure tags (no existing div)...
+		if ( FIG_END.test( parent.children[ index+1 ].value ) ) {
+			debug( 'Inserting new node...' );
+			parent.children.splice( index+1, 0, divNode );
+		}
+		// Case 2: replace existing single node...
+		else if (
+			FIG_END.test( parent.children[ index+2 ].value )
+		) {
+			debug( 'Replacing existing div node...' );
+			parent.children[ index+1 ] = divNode;
+		}
+		else {
+			debug( 'Invalid node: %s', node.value );
+			throw new Error( format( 'invalid node. Invalid figure comment. Ensure that the Markdown file includes both starting and ending figure comments. Node: `%s`.', node.value ) );
+		}
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = insertFigures;

lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/lib/main.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';
+
+// MODULES //
+
+var transformer = require( './transformer.js' );
+
+
+// MAIN //
+
+/**
+* Attaches a plugin to a remark processor in order to insert image figure elements.
+*
+* @returns {Function} transformer
+*/
+function attacher() {
+	return transformer;
+}
+
+
+// EXPORTS //
+
+module.exports = attacher;