textlint-rule-allowed-uris

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

Click here to view the documentation for textlint-rule-allowed-uris@1.

[!IMPORTANT]

1. Support both textlint v14 and v15. (Supports current and previous major versions of textlint.)

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

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 code. these all types are considered.

• You can also check out the AST Tree of the above examples.

Only URIs are inspected?

No! This rule checks 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 allowed 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@latest textlint@latest

yarn

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

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
      },
      checkUnusedDefinitions?: boolean, // Optional
    }
  }
}

Types

You can import Options type from textlint-rule-allowed-uris package.

import type { Options } from "textlint-rule-allowed-uris";

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/],
           },
           checkUnusedDefinitions: false,
         }
       }
     }

   • Default value passed: [/.*/u]

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/],
           },
           checkUnusedDefinitions: false,
         }
       }
     }

   • Default value passed: [/.*/u]

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/],
           },
           checkUnusedDefinitions: false,
         }
       }
     }

   • 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
           },
           checkUnusedDefinitions: false,
         }
       }
     }

   • Default value passed: []

5. checkUnusedDefinitions: boolean, Optional

   • If set to true, the rule will check for unused definitions and report them as problems.

   • If set to false or not specified, the rule will not check for unused definitions.

   • Definitions that use // are treated as comments and always ignored.

     [//]: # (This behaves like a comment)

   • Default value passed: false

Example (.textlintrc.js)

module.exports = {
  rules: {
    "allowed-uris": {
      allowed: {
        links: [
          // regular expressions
        ],
        images: [
          // regular expressions
        ],
      },
      disallowed: {
        links: [
          // regular expressions
        ],
        images: [
          // regular expressions
        ],
      },
      checkUnusedDefinitions: true, // Optional, default is `false`
    }
  }
}

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 src/textlint-rule-allowed-uris.md --rulesdir ./src -f pretty-error

textlint-rule-allowed-uris: allowed.links
- problem: 'mailto:[email protected]'
- allowed regular expressions: '/google/'
textlint-rule-allowed-uris/src/textlint-rule-allowed-uris.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/src/textlint-rule-allowed-uris.md:15:1
        v
    14.
    15. <[email protected]>
    16.
        ^

textlint-rule-allowed-uris: allowed.links
- problem: ''
- allowed regular expressions: '/google/'
textlint-rule-allowed-uris/src/textlint-rule-allowed-uris.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/src/textlint-rule-allowed-uris.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/src/textlint-rule-allowed-uris.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/src/textlint-rule-allowed-uris.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/src/textlint-rule-allowed-uris.md:101:1
         v
    100.
    101. [linkLocal1]: /README.md "Hello README"
    102.
         ^

✖ 7 problems (7 errors, 0 warnings)

-f stylish option

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

textlint-rule-allowed-uris/src/textlint-rule-allowed-uris.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

✖ 7 problems (7 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 code. 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 code.

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 "<type>[scope]: <description>"

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. (NOTE: Textlint started supporting these types since v14.5.0!)

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
        }
    };
};

In other words, 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.

Code of Conduct

See Code of Conduct.

Change Log

See Change Log.

Versioning

This project adheres to Semantic Versioning.

Security

See Security.

License

MIT