remark-usage
remark plugin to add a usage example to a readme.
Contents
What is this?
This package is a unified (remark) plugin to add a Usage section to markdown.
unified is a project that transforms content with abstract syntax trees (ASTs). remark adds support for markdown to unified. mdast is the markdown AST that remark uses. This is a remark plugin that transforms mdast.
When should I use this?
You can use this on readmes of npm packages to keep the docs in sync with the project through an actual code sample.
Install
This package is ESM only. In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:
npm install remark-usage
Use
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/readme.md:
# PI
More than enough 🍰
## Usage
## License
MIT
…and an example script to document it example/example.js:
// Load dependencies:
import {pi} from './index.js'
// Logging `pi` yields:
console.log('txt', pi)
…If we use remark-usage, we can generate the Usage section
import {readSync} from 'to-vfile'
import {remark} from 'remark'
import remarkUsage from 'remark-usage'
const file = readSync({path: 'readme.md', cwd: 'example'})
const result = await remark().use(remarkUsage).process(file)
Now, printing result (the newly generated readme) yields:
# PI
More than enough 🍰
## Usage
Load dependencies:
```javascript
import {pi} from 'pi'
```
Logging `pi` yields:
```txt
3.14159
```
## License
MIT
API
This package exports no identifiers. The default export is remarkUsage.
unified().use(remarkUsage[, options])
Add example.js to the Usage section in a readme.
Replaces the current content between the heading containing the text “usage” (configurable) and the next heading of the same (or higher) rank with the example.
The example is run in Node.js. Make sure no side effects occur when running example.js. 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 may help to compare example.js with the above use section.
You can ignore lines like so:
// remark-usage-ignore-next
const 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.
options
options.heading
Heading to look for (string?, default: 'usage'). Wrapped in new RegExp('^(' + value + ')$', 'i');.
options.example
Path to the example (string?). If given, resolved from file.cwd. If not given, the following values are attempted and resolved from file.cwd: './example.js', './example/index.js', './examples.js', './examples/index.js', './doc/example.js', './doc/example/index.js', './docs/example.js', './docs/example/index.js'. The first that exists, is used.
options.name
Name of the module (string?, default: pkg.name, optional). Used to rewrite require('.') to require('name').
options.main
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').
Types
This package is fully typed with TypeScript. It exports an Options type, which specifies the interface of the accepted options.
Compatibility
Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 12.20+, 14.14+, and 16.0+. Our projects sometimes work with older versions, but this is not guaranteed.
This plugin works with remark version 12+ and remark-cli version 8+.
Security
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.
Related
remark-toc— add a table of contents (TOC)remark-license— add a license sectionremark-contributors— add a contributors section
Contribute
See contributing.md in remarkjs/.github for ways to get started. See support.md 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.