Nimble Pirate Monitor

    remark-license
    TypeScript icon, indicating that this package has built-in type declarations

    6.1.0 • Public • Published

    remark-license

    Build Coverage Downloads Size Sponsors Backers Chat

    remark plugin to generate a license section.

    Contents

    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 file example.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’s package.json and license 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. In short, this plugin:

    • looks for the heading matching /^licen[cs]e$/i or options.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 an Options 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) 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

    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

    Install

    npm i remark-license

    DownloadsWeekly Downloads

    195

    Version

    6.1.0

    License

    MIT

    Unpacked Size

    20.6 kB

    Total Files

    15

    Last publish

    Collaborators

    • johno
    • wooorm