remark plugin to add a usage example to your readme
Last updated 10 months ago by wooorm .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install remark-usage 
SYNC missed versions from official npm registry.


Build Coverage Downloads Size Sponsors Backers Chat

remark plugin to add a usage example to a readme.


This plugin is ready for the new parser in remark (remarkjs/remark#536). No change is needed: it works exactly the same now as it did before!



npm install remark-usage


This section is rendered by this module from example.js. Turtles all the way down. ????????????

Say we are making a module that exports just enough Pi (3.14159). We’re documenting it with a readme file, example/

# PI

More than enough ????

## Usage

## License


…and an example script to document it example/example.js:

// Load dependencies:
var pi = require('.')

// Logging `pi` yields:
console.log('txt', pi)

…If we use remark-usage, we can generate the Usage section

var path = require('path')
var vfile = require('to-vfile')
var remark = require('remark')
var usage = require('remark-usage')

var file = vfile.readSync({path: '', cwd: 'example'})

var file = await remark().use(usage).process(file)

Now, printing file (the newly generated readme) yields:

# PI

More than enough ????

## Usage

Load dependencies:

var pi = require('pi')

Logging `pi` yields:


## License



remark().use(usage[, options])

Add example.js to the Usage section in a readme.

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 in Node. 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
  • Make sure no side effects occur when running example.js

You can ignore lines like so:

// remark-usage-ignore-next
var two = sum(1, 1)

// remark-usage-ignore-next 3
function sum(a, b) {
  return a + b

…if no skip is given, 1 line is skipped.


Heading to look for (string?, default: 'usage'). Wrapped in new RegExp('^(' + value + ')$', 'i');.


Path to the example script (string?). If given, resolved from file.cwd. If not given, the following values are attempted and resolved from file.cwd: './example', './examples', './doc/example', './docs/example'. The first that exists, is used.

Name of the module (string?, default:, optional). Used to rewrite require('.') to require('name').


Path to the main file (string?, default: pkg.main or '.', optional). If given, resolved from file.cwd. If inferred from package.json, resolved relating to that package root. Used to rewrite require('.') to require('name').


Pass --experimental-modules when running the example in Node. This lets you use ECMAScript Modules if the current version of Node does support this flag, but does not support ES modules natively.


Use of remark-usage is unsafe because main and example are executed. This could become dangerous if an attacker was able to inject code into those files or their dependencies.


See in remarkjs/.github for ways to get started. See for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.


MIT © Titus Wormer

Current Tags

  • 9.0.0                                ...           latest (3 months ago)
  • 4.0.0-alpha.1                                ...           next (5 years ago)

20 Versions

  • 9.0.0                                ...           3 months ago
  • 8.0.0                                ...           10 months ago
  • 7.0.1                                ...           2 years ago
  • 7.0.0                                ...           2 years ago
  • 6.1.4                                ...           2 years ago
  • 6.1.3                                ...           2 years ago
  • 6.1.2                                ...           2 years ago
  • 6.1.1                                ...           2 years ago
  • 6.1.0                                ...           2 years ago
  • 6.0.1                                ...           2 years ago
  • 6.0.0                                ...           4 years ago
  • 5.0.1                                ...           4 years ago
  • 5.0.0                                ...           4 years ago
  • 4.0.1                                ...           4 years ago
  • 4.0.0                                ...           5 years ago
  • 4.0.0-alpha.1                                ...           5 years ago
  • 3.0.0                                ...           5 years ago
  • 2.1.0                                ...           5 years ago
  • 2.0.1                                ...           5 years ago
  • 2.0.0                                ...           5 years ago

Copyright 2014 - 2017 © |