diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/README.md b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/README.md new file mode 100644 index 000000000000..fe3f42eef5a3 --- /dev/null +++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/README.md @@ -0,0 +1,149 @@ + + +# Image Figure Source URLs + +> [remark][remark] plugin to insert source URLs for figure images into Markdown figure elements. + +
+ +## 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 ); +``` + +
+ + + +
+ +## 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 + + + + ``` + + Here, the implementation would assume that the figure image filename is `figure_padding.svg`, where `figure_` is the default filename prefix. + +
+ + + +
+ +## Examples + + + + + +```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 ); +``` + +
+ + + + + + + + + + + + + + diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/examples/fixtures/doc/img/padding.svg b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/examples/fixtures/doc/img/padding.svg new file mode 100644 index 000000000000..373d25fe14a4 --- /dev/null +++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/examples/fixtures/doc/img/padding.svg @@ -0,0 +1 @@ + diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/examples/fixtures/simple.txt b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/examples/fixtures/simple.txt new file mode 100644 index 000000000000..0406a2328124 --- /dev/null +++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/examples/fixtures/simple.txt @@ -0,0 +1,20 @@ +# Padding + + + +
+ +Padding around chart area: + + + +
+ Padding diagram +
+
+ + + +
+ + diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/examples/index.js b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/examples/index.js new file mode 100644 index 000000000000..29771a86b264 --- /dev/null +++ b/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 ); diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/lib/attacher.js b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/lib/attacher.js new file mode 100644 index 000000000000..a78fdd8858e2 --- /dev/null +++ b/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; diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/lib/defaults.json b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/lib/defaults.json new file mode 100644 index 000000000000..cbdcea2a1486 --- /dev/null +++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/lib/defaults.json @@ -0,0 +1,4 @@ +{ + "dir": "./docs/img/", + "prefix": "figure_" +} diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/lib/git.js b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/lib/git.js new file mode 100644 index 000000000000..56ad2e4f58a9 --- /dev/null +++ b/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; diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/lib/index.js b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/lib/index.js new file mode 100644 index 000000000000..106d0ccb82e9 --- /dev/null +++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/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 source URLs for figure images into Markdown figure elements. +* +* @module @stdlib/_tools/remark/plugins/remark-img-figures-src-urls +* +* @example +* var remark = require( 'remark' ); +* var insertURLs = require( '@stdlib/_tools/remark/plugins/remark-img-figures-src-urls' ); +* +* var transform = remark().use( insertURLs ).processSync; +*/ + +// MODULES // + +var attacher = require( './attacher.js' ); + + +// EXPORTS // + +module.exports = attacher; diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/lib/transformer.js b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/lib/transformer.js new file mode 100644 index 000000000000..343068955581 --- /dev/null +++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/lib/transformer.js @@ -0,0 +1,138 @@ +/** +* @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 resolve = require( 'path' ).resolve; +var join = require( 'path' ).join; +var logger = require( 'debug' ); +var visit = require( 'unist-util-visit' ); +var PATH_SEP = require( '@stdlib/constants/path/sep' ); +var trim = require( '@stdlib/string/trim' ); +var format = require( '@stdlib/string/format' ); +var jsdelivr = require( '@stdlib/_tools/utils/jsdelivr-url' ); +var git = require( './git.js' ); + + +// VARIABLES // + +var debug = logger( 'remark-img-figures-src-urls:transformer' ); +var DIV_FIG = /
` tag: + node.value = node.value.replace( IMG_SOURCE, '$1' + url + '$3' ); + } + } + } +} + + +// EXPORTS // + +module.exports = factory; diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/package.json b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/package.json new file mode 100644 index 000000000000..1a2a04bd58c1 --- /dev/null +++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures-src-urls/package.json @@ -0,0 +1,53 @@ +{ + "name": "@stdlib/_tools/remark/plugins/remark-img-figures-src-urls", + "version": "0.0.0", + "description": "remark plugin to insert source URLs for figure images into Markdown figure elements.", + "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": ">=0.10.0", + "npm": ">2.7.0" + }, + "keywords": [ + "tools", + "markdown", + "md", + "mdown", + "html", + "figure", + "fig", + "svg", + "image", + "img", + "remote", + "remark", + "mdast", + "plugin", + "github" + ] +}