remark-usage

remark-usage

Add a usage example to a README.

:warning: mdast is currently being renamed to remark :warning:

This means all plug-ins and relating projects change too, causing many changes across the ecosystem. Expect the dust to settle in roughly a day.

See this project at the previous stable commit c4a51d1.

Installation

npm:

npm install remark-usage

Usage

This section is rendered by this module from example.js.

Require dependencies:

var fs = require('fs');
var remark = require('remark');

Require usage:

/*
 * The below is changed because a require to the main
 * module file is detected.
 */
var usage = require('remark-usage'); // This is changed from `./index.js` to `remark-usage`

Read and parse readme.md:

var readme = fs.readFileSync('readme.md', 'utf-8');
var ast = remark.use(usage).parse(readme);

Log something with a language flag:

Add a [usage](#usage) example to a README.

Or without language:

## Installation

Log something which is never captured:

function neverCalled() {
    console.log('javascript', 'alert("test")');
}

Log something which isn’t captured because it’s not not a string.

console.log(this);

API

remark.use(usage, options)

Adds example.js to the Usage section in a readme.md.

Removes the current content between the heading containing the text “usage”, and the next heading of the same (or higher) depth, and replaces it with the example.

The example is run as JavaScript. Line comments are parsed as Markdown. Calls to console.log() are exposed as code blocks, containing the logged values (optionally with a language flag).

It’s easiest to check out and compare example.js with the above Usage section.

• Operate this from an npm package, or provide a cwd;
• Make sure no side effects occur when running example.js!
• Don’t do weird things. This is mostly regexes!

You can provide options to remark.use():

Options:

• cwd (string?) — Path to a directory containing a node module. Used to infer name, main, and example;

• name (string?) — Name of the module. Inferred from package.jsons name property. Used to rewrite require('./index.js') to require('some-name');

• main (string?) — Path to the main script. Resolved from package.jsons main property (or index.js). Used to rewrite require('./index.js') to require('some-name').

• example (string?) — Path to the example script. remark-usage checks for docs/example.js, doc/example.js, examples/index.js, example/index.js, and example.js.

License

MIT © Titus Wormer