README.md

Includes

remark plugin to insert content from external Markdown files.

Usage

var includes = require( '@stdlib/_tools/remark/plugins/remark-includes' );

includes( [options] )

Attaches a plugin to a remark processor in order to insert content from external Markdown files between include comment directives.

var join = require( 'path' ).join;
var remark = require( 'remark' );

var opts = {
    'dir': join( __dirname, 'snippets' )
};

var str = '# Hello World!\n';
str += '\n';
str += '<!-- <include path="./foo.md"> -->\n';
str += '\n';
str += '<!-- </include> -->\n';

var vfile = remark().use( includes, opts ).processSync( str );

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.

The plugin recognizes HTML comments of the form

<!-- <include path="./relative/path/to/file.md"> -->

<!-- </include> -->

and inserts the parsed Markdown content of the referenced file between the opening and closing comment tags.

The opening include directive requires a path attribute with a double-quoted value.

Include blocks must be non-overlapping sibling regions. Nested or overlapping include blocks are not supported.

The plugin accepts the following options:

• dir: base directory for resolving include paths. Default: null (resolved relative to the processed file's directory).

If a referenced file cannot be found, the plugin issues a warning and leaves the include block unchanged.

If an opening include directive does not have a matching closing include directive, the plugin issues a warning and leaves the include block unchanged.

Examples

var join = require( 'path' ).join;
var remark = require( 'remark' );
var readFileSync = require( '@stdlib/fs/read-file' ).sync;
var includes = require( '@stdlib/_tools/remark/plugins/remark-includes' );

// Load a Markdown file...
var fpath = join( __dirname, 'examples', 'fixtures', 'simple.txt' );
var opts = {
    'encoding': 'utf8'
};
var file = readFileSync( fpath, opts );

// Insert includes:
var vfile = remark().use( includes, {
    'dir': join( __dirname, 'examples', 'fixtures' )
}).processSync( file );

console.log( vfile.contents );