Security News
RubyGems.org Adds New Maintainer Role
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
remark-usage
Advanced tools
remark plugin to add a usage example to a readme.
This package is a unified (remark) plugin to add a usage section to markdown.
You can use this on readmes of npm packages to keep the docs in sync with the project through an actual code sample.
This package is ESM only. In Node.js (version 16+), install with npm:
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/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
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.
options
(Options
, optional)
— configurationTransform (Transformer
).
Options
Configuration (TypeScript type).
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'
This package is fully typed with TypeScript.
It exports the additional type Options
.
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+.
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.
remark-toc
— add a table of contents (TOC)remark-license
— add a license sectionremark-contributors
— add a contributors sectionSee 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.
FAQs
remark plugin to add a usage example to your readme
The npm package remark-usage receives a total of 1,981 weekly downloads. As such, remark-usage popularity was classified as popular.
We found that remark-usage demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
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.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.