diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/README.md b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/README.md new file mode 100644 index 000000000000..1c0fd291ab92 --- /dev/null +++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/README.md @@ -0,0 +1,114 @@ + + +# Image Figures + +> [remark][remark] plugin to insert Markdown image figure elements. + +
+ +## 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. + + + +```javascript +var remark = require( 'remark' ); + +var str = 'Padding around chart area:'; +str += '\n'; +str += '\n'; +str += '\n'; +str += ''; + +var vfile = remark().use( insertFigures ).processSync( str ); + +console.log( vfile.contents ); +/* => + Padding around chart area: + + + +
+ Padding diagram +
+
+ + +*/ +``` + +
+ + + +
+ +## Examples + + + + + +```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 ); +``` + +
+ + + + + +
+ +
+ + + + + +
+ +[remark]: https://github.com/wooorm/remark + +
+ + diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/examples/fixtures/simple.txt b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/examples/fixtures/simple.txt new file mode 100644 index 000000000000..7de6386464e8 --- /dev/null +++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/examples/fixtures/simple.txt @@ -0,0 +1,18 @@ +# Padding + +
+ +Padding around chart area: + + + +
+ Padding diagram +
+
+ + + +
+ + diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/examples/index.js b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/examples/index.js new file mode 100644 index 000000000000..e8a12fa1adbc --- /dev/null +++ b/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 ); diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/lib/index.js b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/lib/index.js new file mode 100644 index 000000000000..f179c7ef26f9 --- /dev/null +++ b/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; diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/lib/insert_figures.js b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/lib/insert_figures.js new file mode 100644 index 000000000000..b69b020900f3 --- /dev/null +++ b/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 = //; +var FIG_END = //; +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; diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/lib/main.js b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/lib/main.js new file mode 100644 index 000000000000..a7057971418c --- /dev/null +++ b/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; diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/lib/transformer.js b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/lib/transformer.js new file mode 100644 index 000000000000..c99eedb79482 --- /dev/null +++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/lib/transformer.js @@ -0,0 +1,49 @@ +/** +* @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 visit = require( 'unist-util-visit' ); +var visitor = require( './insert_figures.js' ); + + +// VARIABLES // + +var debug = logger( 'remark-img-figures:transformer' ); + + +// MAIN // + +/** +* Transforms a Markdown abstract syntax tree (AST). +* +* @private +* @param {Node} tree - root AST node +*/ +function transformer( tree ) { + debug( 'Processing virtual file...' ); + visit( tree, 'html', visitor ); +} + + +// EXPORTS // + +module.exports = transformer; diff --git a/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/package.json b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/package.json new file mode 100644 index 000000000000..98bfcfc3f31b --- /dev/null +++ b/lib/node_modules/@stdlib/_tools/remark/plugins/remark-img-figures/package.json @@ -0,0 +1,55 @@ +{ + "name": "@stdlib/_tools/remark/plugins/remark-img-figures", + "version": "0.0.0", + "description": "remark plugin to insert image 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", + "image", + "img", + "visualization", + "chart", + "compile", + "transform", + "remark", + "mdast", + "plugin", + "github" + ] +}