Skip to content

sijeesh-02/remark-usage

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

76 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

remark-usage Build Status Coverage Status Chat

Add a usage example to a README with remark.

Installation

npm:

npm install remark-usage

Usage

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

Dependencies:

var fs = require('fs');
var remark = require('remark');
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:

## Installation

Or without language:

[npm][]:

Log something which is never captured:

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

Log something which isn’t captured because it’s 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
options
options.cwd

string? — Path to a directory containing a node module. Used to infer name, main, and example.

options.name

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

options.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').

options.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.

options.heading

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

License

MIT © Titus Wormer

About

Add a usage example to your Readme

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 100.0%