Textlint-rule-allowed-uris NPM

textlint-rule-allowed-uris

A textlint rule for checking allowed or disallowed URIs in links and images of Markdown.🔥

!IMPORTANT
This rule only supports Markdown(.md or .mdx) files. Note that it does not recognize URIs in ~~Text~~(.txt) files.
The linting process includes HTTP requests, so an internet connection is required. Otherwise, an error will occur.
Note that every URIs should be recognized by Markdown. URIs which are not recognized by Markdown cannot be inspected. For example, URIs without https://... or http://....
www.google.com
<www.google.com>

Features

Supported

You can use any link or image formats which are supported by Markdown. (Even HTML tags are available!)

Click to see detailed Markdown examples. Look at raw codes. these all types are considered.
You can also check out the AST Tree of the above examples.

Only URIs are inspected?

No! We check not only for URIs, but also for local paths. Below patterns are inspected too.

README.md (Relative path)
/README.md (Absolute path)
../README.md (Relative path)
/learn/start-a-new-react-project#can-i-use-react-without-a-framework (With hash)
/images/languages/javascript/composition-of-javascript/2.png?raw=true (With query parameters)
And more...

Patterns

Only regular expressions are used for URIs pattern matching. You can define the pattern you want to inspect by yourself.

Allowed URIs

Related: allowed.links, allowed.images

Allowed URIs act like an whitelist. Only those written on the whitelist can pass through.

For example, If you pass an empty array to the option, it allows nothing. i.e. Every links or images will be detected. (For a detailed explanation, see Configs.)

Disallowed URIs

Related: disallowed.links, disallowed.images

On the contrary, disallowed URIs act like an blacklist. Only those written on the blacklist cannot pass through.

For example, If you pass an empty array to the option, it allows everything. i.e. no links or images will be detected. (For a detailed explanation, see Configs.)

Installation

`npm`

npm install --save-dev textlint-rule-allowed-uris

`yarn`

yarn add --dev textlint-rule-allowed-uris

Configs

Interface

Every options are optional. If you pass nothing, then nothing just happens!

{
  rules: {
    "allowed-uris": {
      allowed?: { // Optional
        links?: RegExp[], // Optional
        images?: RegExp[], // Optional
      },
      disallowed?: { // Optional
        links?: RegExp[], // Optional
        images?: RegExp[], // Optional
      },
    }
  }
}

Options

allowed.links: RegExp[], Optional

Allowed links act like an whitelist. Only those written on the whitelist can pass through.

If you want to turn off this option, then pass nothing. NOTE: DO NOT PASS AN EMPTY ARRAY TO TURN OFF THIS OPTION.

/* .textlintrc.js */
// Correct way of turning off this option.
module.exports = {
  rules: {
    "allowed-uris": {
      allowed: {
        // links: [], => turned off
        images: [/example/],
      },
      disallowed: {
        links: [/example/],
        images: [/example/],
      },
    }
  }
}

Default value passed: [/.*/]

allowed.images: RegExp[], Optional

Allowed images act like an whitelist. Only those written on the whitelist can pass through.

If you want to turn off this option, then pass nothing. NOTE: DO NOT PASS AN EMPTY ARRAY TO TURN OFF THIS OPTION.

/* .textlintrc.js */
// Correct way of turning off this option.
module.exports = {
  rules: {
    "allowed-uris": {
      allowed: {
        links: [/example/],
        // images: [], => turned off
      },
      disallowed: {
        links: [/example/],
        images: [/example/],
      },
    }
  }
}

Default value passed: [/.*/]

disallowed.links: RegExp[], Optional

Disallowed links act like an blacklist. Only those written on the blacklist cannot pass through.

If you want to turn off this option, then pass nothing. or here, you can pass an empty array. (because the default value passed is an empty array too.)

/* .textlintrc.js */
// Correct way of turning off this option.
module.exports = {
  rules: {
    "allowed-uris": {
      allowed: {
        links: [/example/],
        images: [/example/],
      },
      disallowed: {
        // links: [], => turned off
        images: [/example/],
      },
    }
  }
}

Default value passed: []

disallowed.images: RegExp[], Optional

Disallowed images act like an blacklist. Only those written on the blacklist cannot pass through.

If you want to turn off this option, then pass nothing. or here, you can pass an empty array. (because the default value passed is an empty array too.)

/* .textlintrc.js */
// Correct way of turning off this option.
module.exports = {
  rules: {
    "allowed-uris": {
      allowed: {
        links: [/example/],
        images: [/example/],
      },
      disallowed: {
        links: [/example/],
        // images: [], => turned off
      },
    }
  }
}

Default value passed: []

Example (`.textlintrc.js`)

module.exports = {
  rules: {
    "allowed-uris": {
      allowed: {
        links: [
          // regular expressions
        ],
        images: [
          // regular expressions
        ],
      },
      disallowed: {
        links: [
          // regular expressions
        ],
        images: [
          // regular expressions
        ],
      },
    }
  }
}

Usages

textlint [options] file.md [file|dir|glob*]

Without a config file

npx textlint --rule allowed-uris -f pretty-error file.md

With a config file

npx textlint -f pretty-error file.md

Sample Outputs

When configured like below.

module.exports = {
  rules: {
    "allowed-uris": {
      allowed: {
        links: [/google/],
      },
    }
  }
}

`-f pretty-error` option

> npx textlint tests/textlint-rule-allowed-uris.data.md --rulesdir ./src -f pretty-error

textlint-rule-allowed-uris: allowed.links
- problem: 'mailto:example@gmail.com'
- allowed regular expressions: '/google/'
textlint-rule-allowed-uris/tests/textlint-rule-allowed-uris.data.md:9:1
        v
     8.
     9. example@gmail.com
    10.
        ^

textlint-rule-allowed-uris: allowed.links
- problem: 'mailto:example@gmail.com'
- allowed regular expressions: '/google/'
textlint-rule-allowed-uris/tests/textlint-rule-allowed-uris.data.md:15:1
        v
    14.
    15. <example@gmail.com>
    16.
        ^

textlint-rule-allowed-uris: allowed.links
- problem: ''
- allowed regular expressions: '/google/'
textlint-rule-allowed-uris/tests/textlint-rule-allowed-uris.data.md:21:1
        v
    20.
    21. [google]() <!-- empty link -->
    22.
        ^

textlint-rule-allowed-uris: allowed.links
- problem: '#heading'
- allowed regular expressions: '/google/'
textlint-rule-allowed-uris/tests/textlint-rule-allowed-uris.data.md:23:1
        v
    22.
    23. [title](#heading) <!-- hash(fragment) -->
    24.
        ^

textlint-rule-allowed-uris: allowed.links
- problem: '../README.md'
- allowed regular expressions: '/google/'
textlint-rule-allowed-uris/tests/textlint-rule-allowed-uris.data.md:25:1
        v
    24.
    25. [README.md](../README.md) <!-- relative path -->
    26.
        ^

textlint-rule-allowed-uris: allowed.links
- problem: 'https://en.wikipedia.org/wiki/File:Example.jpg'
- allowed regular expressions: '/google/'
textlint-rule-allowed-uris/tests/textlint-rule-allowed-uris.data.md:86:1
        v
    85.
    86. [![example](https://upload.wikimedia.org/wikipedia/en/a/a9/Example.jpg "Example Image")](https://en.wikipedia.org/wiki/File:Example.jpg)
    87.
        ^

textlint-rule-allowed-uris: allowed.links
- problem: '/README.md'
- allowed regular expressions: '/google/'
textlint-rule-allowed-uris/tests/textlint-rule-allowed-uris.data.md:101:1
         v
    100.
    101. [linkLocal1]: /README.md "Hello README"
    102.
         ^

textlint-rule-allowed-uris: allowed.links
- problem: '/LICENSE'
- allowed regular expressions: '/google/'
textlint-rule-allowed-uris/tests/textlint-rule-allowed-uris.data.md:103:1
         v
    102.
    103. [neverUsed]: /LICENSE "neverUsed"
    104.
         ^

✖ 8 problems (8 errors, 0 warnings)

`-f stylish` option

> npx textlint tests/textlint-rule-allowed-uris.data.md --rulesdir ./src -f stylish

textlint-rule-allowed-uris/tests/textlint-rule-allowed-uris.data.md
    9:1  error  allowed.links
- problem: 'mailto:example@gmail.com'
- allowed regular expressions: '/google/'                    textlint-rule-allowed-uris
   15:1  error  allowed.links
- problem: 'mailto:example@gmail.com'
- allowed regular expressions: '/google/'                    textlint-rule-allowed-uris
   21:1  error  allowed.links
- problem: ''
- allowed regular expressions: '/google/'                    textlint-rule-allowed-uris
   23:1  error  allowed.links
- problem: '#heading'
- allowed regular expressions: '/google/'                    textlint-rule-allowed-uris
   25:1  error  allowed.links
- problem: '../README.md'
- allowed regular expressions: '/google/'                    textlint-rule-allowed-uris
   86:1  error  allowed.links
- problem: 'https://en.wikipedia.org/wiki/File:Example.jpg'
- allowed regular expressions: '/google/'                    textlint-rule-allowed-uris
  101:1  error  allowed.links
- problem: '/README.md'
- allowed regular expressions: '/google/'                    textlint-rule-allowed-uris
  103:1  error  allowed.links
- problem: '/LICENSE'
- allowed regular expressions: '/google/'                    textlint-rule-allowed-uris

✖ 8 problems (8 errors, 0 warnings)

Q&A

How to distinguish email links?

Email links like <example@gmail.com> are interpreted as mailto:example@gmail.com. Therefore, use /^mailto:/ in regular expressions.

Contributing

Thanks for having attention to this package.🙇‍♂️ Issues and PRs are always welcome.🎉

I recommend you to read textlint guides before contributing.

And check out the Installation and Concepts of textlint-rule-allowed-uris guides below. It will help you to understand how this package works.

After that, refer to the comments in source codes. It contains useful information to help you.

Installation

Fork it.

Clone it to your local directory. (Git is required.)

git clone https://github.com/lumirlumir/npm-textlint-rule-allowed-uris.git

Move to the npm-textlint-rule-allowed-uris directory.
```
cd npm-textlint-rule-allowed-uris
```
Install npm packages. (Node.js is required.)
```
npm install
```
Edit codes.
Create my-branch branch.
```
git switch -c my-branch
```
Commit your changes. (husky and lint-staged will lint and test your changed files!)
```
git commit -am "commit type: title"
```
Push them to your remote branch.
Submit a pull request.👍

Concepts of `textlint-rule-allowed-uris`

textlint-rule-allowed-uris rule checks allowed or disallowed URIs in links and images of Markdown.

Detailed node types which are checked by this rule

Links node type
1. Link(ASTNodeTypes.Link)
2. Definition (We don't use ~~LinkReference~~)
3. Html(ASTNodeTypes.Html)
Images node type
1. Image(ASTNodeTypes.Image)
2. Definition (We don't use ~~ImageReference~~)
3. Html(ASTNodeTypes.Html)

!NOTE
LinkReference, ImageReference and Definition are types parsed by @textlint/text-to-ast. But, It is not defined in @textlint/ast-node-types.
However, you can use these three node types. It is described in textlint guides. See below.
Other plugin has defined other node type that is not defined in @textlint/ast-node-types, but you can specify it as just a string.
// A rule can treat "Example" node type
export default () => {
    return {
        ["Example"](node) {
            // do something
        }
    };
};
i.e. you can use other node types that is not defined in @textlint/ast-node-types. like Definition type.