Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

remark-usage

Package Overview
Dependencies
Maintainers
2
Versions
24
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

remark-usage

remark plugin to add a usage example to your readme

  • 11.0.1
  • latest
  • Source
  • npm
  • Socket score

Version published
Maintainers
2
Created
Source

remark-usage

Build Coverage Downloads Sponsors Backers Chat

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.

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 16+), 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 {remark} from 'remark'
import remarkUsage from 'remark-usage'
import {read} from 'to-vfile'

const file = await read({path: 'readme.md', cwd: 'example'})

await remark().use(remarkUsage).process(file)

…then printing file (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 a usage example to a readme.

Looks for the first heading matching options.heading (case insensitive), removes everything between it and an equal or higher next heading, and replaces that with an example.

The example runs in Node.js (so no side effects!). Line comments (//) are turned into markdown. Calls to console.log() are exposed as code blocks, containing the logged values, so console.log(1 + 1) becomes 2. Use a string as the first argument to log to use as the language for the code.

You can ignore lines with remark-usage-ignore-next:

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

Parameters
  • options (Options, optional) — configuration
Returns

Transform (Transformer).

Options

Configuration (TypeScript type).

Fields
  • example (string, optional) — path to example file (optional); resolved from file.cwd; defaults to the first example that exists: 'example.js', 'example/index.js', 'examples.js', 'examples/index.js', 'doc/example.js', 'doc/example/index.js', 'docs/example.js', 'docs/example/index.js'
  • heading (string, default: 'usage') — heading to look for; wrapped in new RegExp('^(' + value + ')$', 'i');
  • main (string, default: pkg.exports, pkg.main, 'index.js') — path to the file; resolved from file.cwd; used to rewrite import x from './main.js' to import x from 'name'
  • name (string, default: pkg.name) — name of the module; used to rewrite import x from './main.js' to import x from 'name'

Types

This package is fully typed with TypeScript. It exports the additional type Options.

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, remark-usage@^11, compatible with Node.js 16.

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.

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.

License

MIT © Titus Wormer

Keywords

FAQs

Package last updated on 02 Nov 2023

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc