remark-license

remark plugin to add a license section to your readme.

Note!

This plugin is ready for the new parser in remark (remarkjs/remark#536). No change is needed: it works exactly the same now as it did before!

Install

npm:

npm install remark-license

Use

Say we have the following file, example.md:

## License

Something nondescript.

And our script, example.js, looks as follows:

var fs = require('fs')
var remark = require('remark')
var license = require('remark-license')

remark()
  .use(license)
  .process(fs.readFileSync('example.md'), function(err, file) {
    if (err) throw err
    console.log(String(file))
  })

Now, running node example yields:

## License

[MIT](LICENSE) © [Titus Wormer](https://wooorm.com)

API

remark().use(license[, options])

Plugin to add a license section to your readme. Adds content to the heading matching /^licen[cs]e$/i or options.heading. Replaces the original content of that section. Does nothing when no heading is found. Does nothing when the processed file is the license file (such for a license heading in license.md).

options

options.name

License holder (string, optional). Detected from the package.json in the current working directory, supporting both object and string format of author. Throws when neither given nor detected.

options.license

SPDX identifier (string, optional). Detected from the license field in the package.json in the current working directory. Deprecated license objects are not supported. Throws when neither given nor detected.

options.file

File name of license file (string, optional). Detected from the files in 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, but options.license is a known SPDX identifier, the URL to the license on spdx.org is used.

options.url

URL to license holder (string, optional). Detected from the package.json in the current working directory, supporting both object and string format of author. http:// is prepended if url starts without HTTP or HTTPS protocol.

options.ignoreFinalDefinitions

Ignore final definitions otherwise in the section (boolean, default: true).

options.heading

Heading to look for (string (case-insensitive) or RegExp, default: /^licen[cs]e$/i).

Detection

Detection of package.json and files in the current working directory is based on the current working directory as set on the given vfile.

If you want to set the cwd yourself (the default is process.cwd()), you can pass in a vfile or vfile options to .process like so:

var fs = require('fs')
var path = require('path')
var remark = require('remark')
var license = require('remark-license')

remark()
  .use(license)
  .process(
    {
      cwd: path.join('.', 'some', 'path', 'to', 'a', 'directory'),
      contents: fs.readFileSync('example.md')
    },
    function(err, file) {
      if (err) throw err
      console.log(String(file))
    }
  )

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 later transformed to rehype (hast) or opened in an unsafe Markdown viewer.

Related

• remark-collapse — Make a section collapsible
• remark-contributors — Add a list of contributors
• remark-toc — Add a table of contents
• remark-usage — Add 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.

License

MIT © Titus Wormer