textlint-rule-allowed-uris

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

[!IMPORTANT]

1. This rule only supports Markdown(.md or .mdx) files. Note that it does not recognize URIs in ~~Text~~(.txt) files.

2. The linting process includes HTTP requests, so an internet connection is required. Otherwise, an error will occur.

3. 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

1. 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: [/.*/]

2. 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: [/.*/]

3. 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: []

4. 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:[email protected]'
- allowed regular expressions: '/google/'
textlint-rule-allowed-uris/tests/textlint-rule-allowed-uris.data.md:9:1
        v
     8.
     9. [email protected]
    10.
        ^

textlint-rule-allowed-uris: allowed.links
- problem: 'mailto:[email protected]'
- allowed regular expressions: '/google/'
textlint-rule-allowed-uris/tests/textlint-rule-allowed-uris.data.md:15:1
        v
    14.
    15. <[email protected]>
    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:[email protected]'
- allowed regular expressions: '/google/'                    textlint-rule-allowed-uris
   15:1  error  allowed.links
- problem: 'mailto:[email protected]'
- 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 <[email protected]> are interpreted as mailto:[email protected]. 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

1. Fork it.

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

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

3. Move to the npm-textlint-rule-allowed-uris directory.

   cd npm-textlint-rule-allowed-uris

4. Install npm packages. (Node.js is required.)

   npm install

5. Edit codes.

6. Create my-branch branch.

   git switch -c my-branch

7. Commit your changes. (husky and lint-staged will lint and test your changed files!)

   git commit -am "commit type: title"

8. Push them to your remote branch.

9. 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

1. Links node type

   1. Link(ASTNodeTypes.Link)
   2. Definition (We don't use ~~LinkReference~~)
   3. Html(ASTNodeTypes.Html)

2. 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.

AST Tree

You can see detailed parsed AST Tree in here. (Already mentioned above.) Look which kind of types are exist for links and images.

Versioning

This project adheres to Semantic Versioning.

Change Log

See CHANGELOG.md

License

MIT