remark-license
!Buildbuild-badgebuild
!Coveragecoverage-badgecoverage
!Downloadsdownloads-badgedownloads
!Sizesize-badgesize
!Sponsorssponsors-badgecollective
!Backersbackers-badgecollective
!Chatchat-badgechatremark plugin to generate a license section.
Contents
* [`unified().use(remarkLicense[, options])`](#unifieduseremarklicense-options)
What is this?
This package is a unified (remark) plugin to generate a license section such as the one below.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?
This project is useful when you’re writing documentation for an open source project, typically a Node.js package, that has one or more readmes and maybe some other markdown files as well. You want to show the author and license associated with the project. When this plugin is used, authors can add a certain heading (say,## License
)
to documents and this plugin will populate them.Install
This package is ESM only. In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:npm install remark-license
In Deno with Skypack:
import remarkLicense from 'https://cdn.skypack.dev/remark-license@6?dts'
In browsers with Skypack:
<script type="module">
import remarkLicense from 'https://cdn.skypack.dev/remark-license@6?min'
</script>
Use
Say we have the following fileexample.md
in this project:# Example
Some text.
## Use
## API
## License
And our module
example.js
looks as follows:import {read} from 'to-vfile'
import {remark} from 'remark'
import remarkLicense from 'remark-license'
main()
async function main() {
const file = await remark()
.use(remarkLicense)
.process(await read('example.md'))
console.log(String(file))
}
Now running
node example.js
yields:# Example
Some text.
## Use
## API
## License
[MIT](license) © [Titus Wormer](https://wooorm.com)
👉 Note: This info is inferred from this project’spackage.json
package-json andlicense
license file. Running this example in a different package will yield different results.
API
This package exports no identifiers. The default export isremarkLicense
.unified().use(remarkLicense[, options])
Generate a license section.
In short, this plugin:- looks for the heading matching
/^licen[cs]e$/i
oroptions.heading
. - if there is a heading, replaces it with a new section
options
Configuration (optional in Node.js, required in browsers).options.name
License holder (string
).
In Node.js, defaults to the author
field in the closest package.json
.
Throws when neither given nor detected.options.license
SPDX identifier (string
).
In Node.js, defaults to the license
field in the closest package.json
.
Throws when neither given nor detected.options.file
File name of license file (string
, optional).
In Node.js, defaults to a file in the directory of the closest package.json
that matches /^licen[cs]e(?=$|\.)/i
.
If there is no given or found license file, but options.license
is a known
SPDX identifier, then the URL to the license on spdx.org
is used.options.url
URL to license holder (string
, optional).
In Node.js, defaults to the author
field in the closest package.json
.
http://
is prepended if url
does not start with an HTTP or HTTPS protocol.options.ignoreFinalDefinitions
Ignore definitions that would otherwise trail in the section (boolean
,
default: true
).options.heading
Heading to look for (string
(case insensitive) or RegExp
, default:
/^licen[cs]e$/i
).Types
This package is fully typed with TypeScript. It exports anOptions
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
unified
version 6+ and remark
version 7+.Security
options.url
(or author.url
in package.json
) is used and injected into the
tree when it’s given or found.
This could open you up to a cross-site scripting (XSS)xss attack if you pass
user provided content in or store user provided content in package.json
.This may become a problem if the markdown is later transformed to rehype (hast) or opened in an unsafe markdown viewer.
Related
– make some sections collapsible
– generate a contributors section
— generate a table of contents
— generate a usage example
Contribute
Seecontributing.md
contributing in remarkjs/.github
health for ways
to get started.
See support.md
support for ways to get help.This project has a code of conductcoc. By interacting with this repository, organization, or community you agree to abide by its terms.