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

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

@@ -0,0 +1,149 @@
+<!--
+
+@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 Figure Source URLs
+
+> [remark][remark] plugin to insert source URLs for figure images into Markdown figure elements.
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var insertURLs = require( '@stdlib/_tools/remark/plugins/remark-img-figures-src-urls' );
+```
+
+#### insertURLs( options )
+
+Attaches a plugin to a [remark][remark] processor in order to insert source URLs for figure images into Markdown figure elements.
+
+```javascript
+var remark = require( 'remark' );
+
+remark().use( insertURLs );
+```
+
+The plugin accepts the following `options`:
+
+-   **dir**: directory containing figure images. Default: `./docs/img/`.
+-   **prefix**: filename prefix. Default: `figure_`.
+
+By default, the plugin attempts to resolve figure images relative to each processed Markdown file. The default directory is `./docs/img/`. To specify an alternative directory, including an absolute directory, set the `dir` option.
+
+```javascript
+var remark = require( 'remark' );
+
+var opts = {
+    'dir': '/path/to/absolute/dir/with/svg/figures'
+};
+
+remark().use( insertURLs, opts );
+```
+
+By default, the plugin assumes figure image files are prefixed with `figure_`. To specify an alternative prefix, set the `prefix` option.
+
+```javascript
+var remark = require( 'remark' );
+
+var opts = {
+    'prefix': '' // <= no prefix
+};
+
+remark().use( insertURLs, opts );
+```
+
+</section>
+
+<!-- /.usage -->
+
+<section class="notes">
+
+## Notes
+
+-   The current working directory of the calling process **must** be part of a git repository.
+
+-   The function assumes that figure images are Scalable Vector Graphics (SVG).
+
+-   When resolving a figure image filepath, the implementation **assumes** that the figure `label` attribute corresponds to the figure image filename.
+
+    ```html
+    <!-- <figure class="figure" align="center" label="fig:padding" src="./docs/img/fig_padding.svg" alt="Padding diagram"> -->
+
+    <!-- </figure> -->
+    ```
+
+    Here, the implementation would assume that the figure image filename is `figure_padding.svg`, where `figure_` is the default filename prefix.
+
+</section>
+
+<!-- /.notes -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint-disable no-sync, n/no-sync -->
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var join = require( 'path' ).join;
+var toVFile = require( 'to-vfile' );
+var remark = require( 'remark' );
+var insertURLs = require( '@stdlib/_tools/remark/plugins/remark-img-figures-src-urls' );
+
+// Load a Markdown file...
+var fpath = join( __dirname, 'examples', 'fixtures', 'simple.txt' );
+var vfile = toVFile.readSync( fpath );
+
+// Specify the directory containing figure images:
+var opts = {
+    'dir': './doc/img/', // relative to Markdown file
+    'prefix': ''         // no prefix
+};
+
+// Insert src URLs:
+var out = remark().use( insertURLs, opts ).processSync( vfile );
+
+// Print the results:
+console.log( out.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/remarkjs/remark
+
+</section>
+
+<!-- /.links -->

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

@@ -0,0 +1,20 @@
+# Padding
+
+<!-- <intro> -->
+
+<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-src-urls/examples/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';
+
+var join = require( 'path' ).join;
+var toVFile = require( 'to-vfile' );
+var remark = require( 'remark' );
+var insertURLs = require( './../lib' );
+
+// Load a Markdown file...
+var fpath = join( __dirname, 'fixtures/simple.txt' );
+var vfile = toVFile.readSync( fpath );
+
+// Specify the directory containing figure images:
+var opts = {
+	'dir': './doc/img/', // relative to Markdown file
+	'prefix': ''         // no prefix
+};
+
+// Insert src URLs:
+var out = remark().use( insertURLs, opts ).processSync( vfile );
+
+// Print the results:
+console.log( out.contents );

lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/lib/attacher.js

@@ -0,0 +1,78 @@
+/**
+* @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-img-figures-src-urls:attacher' );
+
+
+// MAIN //
+
+/**
+* Attaches a plugin to a remark processor in order to insert source URLs for figure images into Markdown figure elements.
+*
+* @param {Options} [options] - plugin options
+* @param {string} [options.dir="./docs/img/"] - resource directory
+* @param {string} [options.prefix="figure_"] - filename prefix
+* @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;
+		}
+		if ( hasOwnProp( options, 'prefix' ) ) {
+			if ( !isString( options.prefix ) ) {
+				throw new TypeError( format( 'invalid option. `%s` option must be a string. Option: `%s`.', 'prefix', options.prefix ) );
+			}
+			opts.prefix = options.prefix;
+		}
+	}
+	debug( 'Attaching a plugin configured with the following options: %s', JSON.stringify( opts ) );
+	return transformerFactory( opts );
+}
+
+
+// EXPORTS //
+
+module.exports = attacher;

lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/lib/defaults.json

@@ -0,0 +1,4 @@
+{
+  "dir": "./docs/img/",
+  "prefix": "figure_"
+}

lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/lib/git.js

@@ -0,0 +1,97 @@
+/**
+* @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 exec = require( 'child_process' ).execSync;
+var logger = require( 'debug' );
+var trim = require( '@stdlib/string/trim' );
+var extname = require( '@stdlib/utils/extname' );
+
+
+// VARIABLES //
+
+var debug = logger( 'remark-img-figures-src-urls:git' );
+
+// Regular expression to extract a repository slug:
+var RE = /(?:.+github\.com)(?:\/|:)(.+)/;
+
+
+// MAIN //
+
+/**
+* Returns git repository info.
+*
+* @private
+* @returns {Object} repository info
+*/
+function git() {
+	var branch;
+	var origin;
+	var slug;
+	var opts;
+	var dir;
+	var cmd;
+	var out;
+	var ext;
+
+	// Get the local git repository path:
+	dir = exec( 'git rev-parse --show-toplevel' );
+	dir = trim( dir.toString() );
+	dir = dir.match( /(.+)/ )[ 1 ];
+	debug( 'Local repository directory: %s', dir );
+
+	opts = {
+		'cwd': dir
+	};
+
+	// Get the current branch:
+	cmd = 'git rev-parse --abbrev-ref HEAD';
+	out = exec( cmd, opts );
+	branch = trim( out.toString() );
+	debug( 'Branch: %s', branch );
+
+	// Get the remote origin:
+	cmd = 'git config --get remote.origin.url';
+	out = exec( cmd, opts );
+	origin = trim( out.toString() );
+	ext = extname( origin ); // e.g., https://github.com/stdlib-js/stdlib.git
+	if ( ext ) {
+		origin = origin.slice( 0, origin.length-ext.length ); // e.g., https://github.com/stdlib-js/stdlib
+	}
+	debug( 'Remote origin: %s', origin );
+
+	// Extract the repository slug:
+	slug = origin.match( RE )[ 1 ];
+	debug( 'Repository slug: %s', slug );
+
+	out = {
+		'dir': dir,
+		'slug': slug,
+		'origin': origin,
+		'branch': branch
+	};
+	return out;
+}
+
+
+// EXPORTS //
+
+module.exports = git;