Skip to content

Commit cb81268

Browse files
headlessNodeheadlessNode
authored
Merge branch 'develop' into nd/brd-sclr-lke
2 parents c9039a1 + 2d234cc commit cb81268

661 files changed

Lines changed: 23145 additions & 1493 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/README.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2026 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
# Includes
22+
23+
> [remark][remark] plugin to insert content from external Markdown files.
24+
25+
<section class="usage">
26+
27+
## Usage
28+
29+
```javascript
30+
var includes = require( '@stdlib/_tools/remark/plugins/remark-includes' );
31+
```
32+
33+
#### includes( \[options\] )
34+
35+
Attaches a plugin to a [remark][remark] processor in order to insert content from external Markdown files between include comment directives.
36+
37+
<!-- eslint-disable node/no-sync -->
38+
39+
```javascript
40+
var join = require( 'path' ).join;
41+
var remark = require( 'remark' );
42+
43+
var opts = {
44+
'dir': join( __dirname, 'snippets' )
45+
};
46+
47+
var str = '# Hello World!\n';
48+
str += '\n';
49+
str += '<!-- <include path="./foo.md"> -->\n';
50+
str += '\n';
51+
str += '<!-- </include> -->\n';
52+
53+
var vfile = remark().use( includes, opts ).processSync( str );
54+
```
55+
56+
The plugin accepts the following options:
57+
58+
- **dir**: base directory for resolving include paths. Default: `null` (i.e., include paths are resolved relative to the processed file's directory).
59+
60+
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.
61+
62+
</section>
63+
64+
<!-- /.usage -->
65+
66+
<section class="notes">
67+
68+
## Notes
69+
70+
- The plugin recognizes HTML comments of the form
71+
72+
```html
73+
<!-- <include path="./relative/path/to/file.md"> -->
74+
75+
<!-- </include> -->
76+
```
77+
78+
and inserts the parsed Markdown content of the referenced file between the opening and closing comment tags.
79+
80+
- The opening include directive requires a `path` attribute with a double-quoted value.
81+
82+
- Include blocks must be non-overlapping sibling regions. Nested or overlapping include blocks are not supported.
83+
84+
- If a referenced file cannot be found, the plugin issues a warning and leaves the include block unchanged.
85+
86+
- If an opening include directive does not have a matching closing include directive, the plugin issues a warning and leaves the include block unchanged.
87+
88+
</section>
89+
90+
<!-- /.notes -->
91+
92+
<section class="examples">
93+
94+
## Examples
95+
96+
<!-- eslint no-undef: "error", node/no-sync: "off" -->
97+
98+
```javascript
99+
var join = require( 'path' ).join;
100+
var remark = require( 'remark' );
101+
var readFileSync = require( '@stdlib/fs/read-file' ).sync;
102+
var includes = require( '@stdlib/_tools/remark/plugins/remark-includes' );
103+
104+
// Load a Markdown file...
105+
var fpath = join( __dirname, 'examples', 'fixtures', 'simple.txt' );
106+
var opts = {
107+
'encoding': 'utf8'
108+
};
109+
var file = readFileSync( fpath, opts );
110+
111+
// Insert includes:
112+
var vfile = remark().use( includes, {
113+
'dir': join( __dirname, 'examples', 'fixtures' )
114+
}).processSync( file );
115+
116+
console.log( vfile.contents );
117+
```
118+
119+
</section>
120+
121+
<!-- /.examples -->
122+
123+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
124+
125+
<section class="related">
126+
127+
</section>
128+
129+
<!-- /.related -->
130+
131+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
132+
133+
<section class="links">
134+
135+
[remark]: https://github.com/wooorm/remark
136+
137+
</section>
138+
139+
<!-- /.links -->

‎lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/fixtures/bar.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## Bap
2+
3+
Bip bop.

‎lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/fixtures/foo.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## Greeting
2+
3+
Beep boop.

‎lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/fixtures/simple.txt‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Hello World!
2+
3+
<!-- <include path="./foo.txt"> -->
4+
5+
<!-- </include> -->
6+
7+
<!-- <include path="./bar.txt"> -->
8+
9+
<!-- </include> -->

‎lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/examples/index.js‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2026 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
var join = require( 'path' ).join;
22+
var remark = require( 'remark' );
23+
var readFileSync = require( '@stdlib/fs/read-file' ).sync;
24+
var includes = require( './../lib' );
25+
26+
// Load a Markdown file...
27+
var fpath = join( __dirname, 'fixtures', 'simple.txt' );
28+
var opts = {
29+
'encoding': 'utf8'
30+
};
31+
var file = readFileSync( fpath, opts );
32+
33+
// Insert includes:
34+
var vfile = remark().use( includes, {
35+
'dir': join( __dirname, 'fixtures' )
36+
}).processSync( file );
37+
38+
// Print the results:
39+
console.log( vfile.contents );

‎lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/attacher.js‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2026 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
// MODULES //
22+
23+
var logger = require( 'debug' );
24+
var copy = require( '@stdlib/utils/copy' );
25+
var isObject = require( '@stdlib/assert/is-plain-object' );
26+
var hasOwnProp = require( '@stdlib/assert/has-own-property' );
27+
var isString = require( '@stdlib/assert/is-string' ).isPrimitive;
28+
var format = require( '@stdlib/string/format' );
29+
var transformerFactory = require( './transformer.js' );
30+
var defaults = require( './defaults.json' );
31+
32+
33+
// VARIABLES //
34+
35+
var debug = logger( 'remark-includes:attacher' );
36+
37+
38+
// MAIN //
39+
40+
/**
41+
* Attaches a plugin to a remark processor in order to insert content from external Markdown files.
42+
*
43+
* @param {Options} [options] - options object
44+
* @param {string} [options.dir] - base directory for resolving include paths
45+
* @throws {TypeError} options argument must be an object
46+
* @throws {TypeError} must provide valid options
47+
* @returns {Function} transformer
48+
*/
49+
function attacher( options ) {
50+
var opts = copy( defaults );
51+
52+
// NOTE: cannot use `arguments.length` check, as `options` may be explicitly passed as `undefined`
53+
if ( options !== void 0 ) {
54+
if ( !isObject( options ) ) {
55+
throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );
56+
}
57+
if ( hasOwnProp( options, 'dir' ) ) {
58+
if ( !isString( options.dir ) ) {
59+
throw new TypeError( format( 'invalid option. `%s` option must be a string. Option: `%s`.', 'dir', options.dir ) );
60+
}
61+
opts.dir = options.dir;
62+
}
63+
}
64+
debug( 'Attaching a plugin configured with the following options: %s', JSON.stringify( opts ) );
65+
return transformerFactory( opts );
66+
}
67+
68+
69+
// EXPORTS //
70+
71+
module.exports = attacher;

‎lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/defaults.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"dir": null
3+
}

‎lib/node_modules/@stdlib/_tools/remark/plugins/remark-includes/lib/index.js‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2026 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
/**
22+
* remark plugin to insert content from external Markdown files.
23+
*
24+
* @module @stdlib/_tools/remark/plugins/remark-includes
25+
*
26+
* @example
27+
* var remark = require( 'remark' );
28+
* var includes = require( '@stdlib/_tools/remark/plugins/remark-includes' );
29+
*
30+
* var transform = remark().use( includes ).processSync;
31+
*/
32+
33+
// MODULES //
34+
35+
var main = require( './attacher.js' );
36+
37+
38+
// EXPORTS //
39+
40+
module.exports = main;

0 commit comments

Comments
 (0)