Awesome
remark-license
remark plugin to generate a license section.
Contents
- What is this?
- When should I use this?
- Install
- Use
- API
- Types
- Compatibility
- Security
- Related
- Contribute
- License
What is this?
This package is a unified (remark) plugin to generate a license section such as the one at the bottom of this readme.
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 16+), install with npm:
npm install remark-license
In Deno with esm.sh
:
import remarkLicense from 'https://esm.sh/remark-license@7'
In browsers with esm.sh
:
<script type="module">
import remarkLicense from 'https://esm.sh/remark-license@7?bundle'
</script>
Use
Say we have the following file example.md
in this project:
# Example
Some text.
## Use
## API
## License
…and a module example.js
:
import {remark} from 'remark'
import remarkLicense from 'remark-license'
import {read} from 'to-vfile'
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’s
package.json
andlicense
file. Running this example in a different package will yield different results.
API
This package exports no identifiers.
The default export is remarkLicense
.
unified().use(remarkLicense[, options])
Generate a license section.
Parameters
options
(Options
, optional) — configuration
Returns
Transform (Transformer
).
Options
Configuration (TypeScript type).
Fields
ignoreFinalDefinitions
(boolean
, default:true
) — ignore definitions at the end of the license sectionfile
(string
, optional) — path to license file; detected from the files in the directory of thepackage.json
if there is one, or the current working directory, in which case the first file matching/^licen[cs]e(?=$|\.)/i
is used; if there is no given or found license file, butoptions.license
is a known SPDX identifier, the URL to the license onspdx.org
is usedheading
(RegExp | string
, default:/^licen[cs]e$/i
) — heading to look forlicense
(string
, optional, example:'mit'
) — SPDX identifier; detected from thelicense
field in thepackage.json
in the current working directory; throws when neither given nor detectedname
(string
, optional) — license holder; detected from thepackage.json
closest to the file supporting bothobject
andstring
format ofauthor
; throws when neither given nor detectedurl
(string
, optional) — URL to license holder; detected from thepackage.json
in the current working directory
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-license@^7
,
compatible with Node.js 16.
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) 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
remark-collapse
– make some sections collapsibleremark-contributors
– generate a contributors sectionremark-toc
— generate a table of contentsremark-usage
— generate a usage example
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.